Request & response examples

Submit a candidate application

POST /api/v1/candidate-reactions

Attachments and GDPR documents are sent inline as base64-encoded content in a single request.


curl --request POST \
  --url 'https://integrations-api.teamio.com/api/v1/candidate-reactions' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "firstName": "Jane",
    "surname": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+420987654321",
    "recruitmentId": 67890,
    "attachments": [
      {
        "filename": "cv.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "contentType": "application/pdf",
        "type": "CV"
      },
      {
        "filename": "cover_letter.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "contentType": "application/pdf",
        "type": "MOTIVATION_LETTER"
      }
    ],
    "gdprNotice": {
      "consentText": {
        "filename": "gdpr_consent.txt",
        "content": "SSBoZXJlYnkgY29uc2VudC4uLg==",
        "contentType": "text/plain",
        "type": "OTHER"
      },
      "validTo": "2027-12-31T23:59:59Z"
    }
  }'

Request fields:

Field	Type	Required	Description
`firstName`	string	yes	Candidate’s first name (max 50 chars)
`surname`	string	yes	Candidate’s last name (max 50 chars)
`email`	string	yes	Valid email address (max 50 chars)
`phone`	string	no	Phone number — digits, spaces, and `+`, `-`, `(`, `)`, `.` (max 50 chars)
`recruitmentId`	number	yes	Teamio recruitment ID the candidate is applying to — found on the position detail page in Teamio (see FAQ)
`attachments`	array	no	List of candidate attachments (CV, cover letter, etc.) — maximum 5 attachments
`attachments[].filename`	string	yes	Filename (max 50 chars)
`attachments[].content`	string	yes	Base64-encoded file content
`attachments[].contentType`	string	yes	MIME type, e.g. `application/pdf` (max 50 chars)
`attachments[].type`	string	yes	`CV`, `MOTIVATION_LETTER`, or `OTHER`
`gdprNotice`	object	yes	GDPR consent information
`gdprNotice.consentText`	object	no*	The consent document shown to the candidate (same structure as an attachment object). Required when `gdprNotice.validTo` is supplied.
`gdprNotice.validTo`	string	no	ISO-8601 datetime (e.g. `2027-12-31T23:59:59Z`) until which the candidate’s explicit consent is valid. Must be in the future. Presence of this field signals explicit consent — omitting it records implicit consent only.

Maximum attachment size per file is 10 MB. This limit applies to individual attachments and the gdprNotice.consentText document.

`validTo` present	`consentText` present	Behaviour
no	no	Implicit consent recorded (`granted: false`)
no	yes	Consent text stored, implicit consent (`granted: false`)
yes	yes	Explicit consent recorded (`granted: true`) with expiry
yes	no	Error — `400 INVALID_GDPR_CONSENT_TEXT`

Response:


{
  "requestUuid": "c3d4e5f6-a7b8-9012-cdef-012345678901"
}

Use the requestUuid UUID to poll the import status.

For best performance, we recommend sending candidate applications sequentially through a queue rather than in parallel. This avoids hitting rate limits and ensures predictable processing order.

Validate a request (sandbox)

Use POST /api/v1/candidate-reactions/test with exactly the same request body to validate your payload without saving anything. Requires Sandbox credentials.


curl --request POST \
  --url 'https://integrations-api.teamio.com/api/v1/candidate-reactions/test' \
  --header 'Authorization: Bearer <sandbox_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{ ... same body as production ... }'

Returns 204 No Content if the payload is valid.

Poll import status

GET /api/v1/candidate-reactions/{requestUuid}


curl --request GET \
  --url 'https://integrations-api.teamio.com/api/v1/candidate-reactions/c3d4e5f6-a7b8-9012-cdef-012345678901' \
  --header 'Authorization: Bearer <access_token>'

Response while processing:


{
  "requestUuid": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "status": "PROCESSING",
  "recruitmentId": 67890,
  "link": null,
  "errorMessage": null,
  "createdAt": "2026-03-04T10:00:00Z",
  "updatedAt": "2026-03-04T10:00:01Z"
}

Response on success:


{
  "requestUuid": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "status": "COMPLETED",
  "recruitmentId": 67890,
  "link": "https://my.teamio.com/recruit/candidate/987654/reaction/67890",
  "errorMessage": null,
  "createdAt": "2026-03-04T10:00:00Z",
  "updatedAt": "2026-03-04T10:00:05Z"
}

Response on failure:


{
  "requestUuid": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "status": "FAILED",
  "recruitmentId": 67890,
  "link": null,
  "errorMessage": "The request must contain a valid recruitmentId.",
  "createdAt": "2026-03-04T10:00:00Z",
  "updatedAt": "2026-03-04T10:00:03Z"
}

Status values:

Status	Description
`PROCESSING`	The request has been received and is being processed
`COMPLETED`	The candidate was successfully imported; `link` points to the candidate record in Teamio
`FAILED`	The import failed; see `errorMessage` for details

Request & response examples

Submit a candidate application

GDPR consent modes

Validate a request (sandbox)

Poll import status