Precandidates API Guide

A precandidate is a person record that still needs extra input before full processing can begin. Use the precandidates API when you know which checks you want to run, but you still need Emptor to collect missing data from the candidate. If you want Sol to call the candidate for a screening or their references, start with a precandidate so Emptor can collect the necessary information.

Live API Reference

See the interactive reference for Create a precandidate, Get precandidates by person ID, and Get precandidate form schema.

When to use precandidates

Precandidates are useful when:

• You have contact information (such as email or phone), but you still need fields such as document_id or another report-specific input.
• You want Emptor to host the data-collection form instead of building your own intake flow.
• You want to identify the person record early, then continue the normal BGC flow after the candidate fills the missing information.
• You want to run workflows such as candidate_screening or reference_check, where the candidate must first provide information that is collected through the precandidate flow.

Report-specific use cases

Some reports depend on the precandidate workflow as part of the operational process, not just as a convenience:

• candidate_screening: create a precandidate with a phone number, because Emptor must call the candidate as part of the workflow.
• reference_check: use a precandidate workflow so the candidate can provide the referee information before the check runs.

End-to-end flow

1. Create the precandidate.
2. Store person_id, precandidate_id, form_url, and country_code.
3. Optionally fetch the form schema to learn which fields Emptor will ask for.
4. Share the hosted form_url with the candidate, or let Emptor Sol collect the missing data by phone.
5. Poll the precandidate until it is submitted.
6. Continue with the standard person and report endpoints using the same person_id.

Important request rule

The public schema marks only country_code as required, but the endpoint description adds a business rule: also send either pipeline_id, pipeline_name, or a custom configuration with reports_enabled and report_settings.

Report-specific requirements

If you are creating a precandidate for candidate_screening, include a phone number because that workflow requires calling the candidate. If you are running reference_check, start with a precandidate so the candidate can provide the referee details needed for the check.

WhatsApp messaging

When a phone number is provided, Emptor Sol will reach out to the candidate through WhatsApp to collect the missing information. In that case, the candidate will receive a message a WhatsApp Flow asking the same questions as can be answered via the form_url.

1. Create a precandidate

Use POST /precandidate to create the record and get the hosted form URL.

export API_KEY="your_api_key"
export BASE_URL="https://api.emptor.io/v3"

curl --request POST \
  --url "$BASE_URL/precandidate" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "X-Api-Key: $API_KEY" \
  --data '{
    "country_code": "PE",
    "pipeline_name": "test-pipeline-pe",
    "email": "candidate@example.com",
    "phone": "+51987654321"
  }'

Example response:

{
  "person_id": "09a3446b-bae9-4a03-8a4a-fcec24f784e4",
  "precandidate_id": "test-precandidate-id",
  "form_url": "https://dashboard.emptor.io/forms/test-precandidate-id",
  "reports_enabled": ["document_id_status"],
  "report_settings": {},
  "email": "candidate@example.com",
  "phone": "+51987654321",
  "country_code": "PE",
  "precandidate_status": "CREATED",
  "pipeline_id": "0ujsszwN8NRY24YaXiTIE2VWDTS",
  "pipeline_name": "test-pipeline-pe",
  "created_at": "2023-01-01T12:00:00.000000",
  "updated_at": "2023-01-01T12:00:00.000000"
}

The most important fields to persist are:

• person_id: the identifier you will later use with the normal person and report endpoints.
• precandidate_id: the precandidate record identifier.
• form_url: the hosted Emptor form that collects the missing input.
• country_code: needed when you switch back to the standard BGC endpoints.

If you are not using a pipeline, you can create a precandidate with reports_enabled plus report_settings instead.

2. Read the form schema before sending the form

Use GET /precandidate/{person_id}/schema/{form_id} to see exactly which fields the hosted form expects.

form_id

In the public API spec, form_id is described as “Precandidate form ID (same as precandidate_id)”.

export PERSON_ID="09a3446b-bae9-4a03-8a4a-fcec24f784e4"
export PRECANDIDATE_ID="test-precandidate-id"

curl --request GET \
  --url "$BASE_URL/precandidate/$PERSON_ID/schema/$PRECANDIDATE_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Example response:

{
  "type": "object",
  "properties": {
    "document_id": {
      "type": "string"
    },
    "city_locode": {
      "description": "2 letter country code and 3 letter city location code.",
      "type": "string"
    }
  },
  "required": ["document_id", "city_locode"]
}

This endpoint is useful when you want to:

• show the candidate which information will be requested,
• validate your own pre-filled data before sending the form,
• understand which fields are missing for the selected pipeline or reports.

3. Track whether the precandidate has been completed

Use GET /precandidate/{person_id} to retrieve the current precandidate records for that person.

curl --request GET \
  --url "$BASE_URL/precandidate/$PERSON_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Example response:

[
  {
    "person_id": "09a3446b-bae9-4a03-8a4a-fcec24f784e4",
    "precandidate_id": "test-precandidate-id",
    "form_url": "https://dashboard.emptor.io/forms/test-precandidate-id",
    "reports_enabled": ["document_id_status"],
    "report_settings": {},
    "email": "candidate@example.com",
    "phone": "+51987654321",
    "country_code": "PE",
    "precandidate_status": "SUBMITTED",
    "pipeline_id": "0ujsszwN8NRY24YaXiTIE2VWDTS",
    "pipeline_name": "test-pipeline-pe",
    "created_at": "2023-01-01T12:00:00.000000",
    "updated_at": "2023-01-01T12:10:00.000000"
  }
]

Two integration details matter here:

• This endpoint returns an array, not a single object.
• The public examples show CREATED after creation and SUBMITTED after the form is completed. The public spec does not publish a full enum, so your client should handle unknown statuses safely.

4. Resume the normal BGC flow after submission

User input is completed through the hosted Emptor Dashboard form or by phone with Emptor Sol.

Once the precandidate has been submitted, continue with the standard person and report endpoints using the same person_id returned at creation time.

Check the person status:

export COUNTRY_CODE="PE"

curl --request GET \
  --url "$BASE_URL/$COUNTRY_CODE/persons/$PERSON_ID/status" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

Get the current report states:

curl --request GET \
  --url "$BASE_URL/$COUNTRY_CODE/reports/$PERSON_ID" \
  --header "Accept: application/json" \
  --header "X-Api-Key: $API_KEY"

That lets you keep the same downstream handling you already use for regular BGC persons.

Recommended integration pattern

• Create the precandidate as soon as you know the contact details of a candidate.
• Persist both IDs and the form_url.
• Fetch the schema if you want to show or validate required fields in your own UI.
• Send the candidate to form_url.
• Poll GET /precandidate/{person_id} until the record is submitted.
• Switch to the normal person status and reports endpoints for the rest of the lifecycle.

Common errors

• 404 Pipeline not found: the supplied pipeline_id or pipeline_name does not exist for your account.
• 404 Precandidate form not found: the person_id or form_id pair does not match an existing hosted form.
• 422 Validation failed: the payload shape is valid JSON, but one or more fields do not pass API validation.

Related endpoints

• List Pipelines
• Get Pipeline Schema
• Get a Person Status
• Get reports