---
title: "RUAF Affiliations"
method: POST
path: "/co/ruaf/affiliations/v1"
tags: ["Colombia", "RUAF"]
---

# RUAF Affiliations

`POST /co/ruaf/affiliations/v1`

## Request

- Base URL: `https://api.croma.run`
- URL: `https://api.croma.run/co/ruaf/affiliations/v1`
- Auth: HTTP bearer

Look up a person's social-security affiliations in Colombia by document number. Requires the date the document was issued. `document_type` defaults to `CC`.

Supports async delivery: set `Prefer: wait=N` for an inline result, pass `callback_url` to receive a POST when ready, or poll `GET /jobs/{id}`.

## Headers

- `Idempotency-Key` string
- `Prefer` string

## Request body

- object
  - `document_type` 'CC' | 'CE' | 'TI' | 'RC' | 'PA' | 'PEP' | 'PPT': Colombian document type. Defaults to `CC`.
  - `document_number` string, required: Colombian cédula. 5-12 digits, no leading zero.
  - `issue_date` string, date, required: Date the document was issued, in yyyy-mm-dd format. For TI and RC, the date of birth.
  - `callback_url` string, uri: POST the job result here when it finishes.

## Response `200`

Successful response

- RuafResponse
  - `data` RuafData, required
    - `found` boolean, required: false when the register has no record for this document.
    - `issue_date_matches` boolean, required: false when the register does not accept the document and issue_date together. It answers the same way whether the date is wrong or the document is not on file, so this does not on its own tell those apart. Nothing else is returned in that case.
    - `document_type` 'CC' | 'CE' | 'TI' | 'RC' | 'PA' | 'PEP' | 'PPT', required: The queried document type, echoed back.
    - `document_type_label` string, required: Human label for the document type.
    - `document_number` string, required: The queried document number, echoed back.
    - `full_name` string, nullable, required: Registered names and surnames, null when not found.
    - `sex` string, nullable, required: Sex as the register reports it ("M" / "F"), when present.
    - `as_of` string, nullable, required: The register's own cut-off date for this report (yyyy-mm-dd).
    - `affiliations` object[], required: Affiliations on record; empty when there are none or the person is not found.
      - `system` string, required: Subsystem the affiliation belongs to: "Salud", "Pensiones", "Riesgos Laborales", "Cesantías", "Compensación Familiar", "Pensionados" or "Programas de Asistencia Social".
      - `entity_name` string, required: Administrator the person is affiliated to.
      - `regime` string, nullable, required: Regime or scheme, e.g. "Contributivo" or "PENSIONES: AHORRO INDIVIDUAL".
      - `status` string, nullable, required: Affiliation status as the source words it, e.g. "Activo", "Retirado", "VIGENTE".
      - `affiliate_type` string, nullable, required: How the person is attached, e.g. "COTIZANTE" or "BENEFICIARIO". Health only.
      - `start_date` string, nullable, required: Affiliation start date (yyyy-mm-dd), or null when the source omits it.
      - `economic_activity` string, nullable, required: Employer's economic activity. Occupational risk only.
      - `location` string, nullable, required: Department and municipality the affiliation is registered in, when reported.
    - `checked_at` string, required: When this answer was read, as an ISO timestamp.

## Other responses

- `202`: Accepted — the result is being computed asynchronously. Poll `job.status_url` (GET /jobs/{id}) or supply `callback_url` to have the result POSTed to you. Returned when `Prefer: wait` elapses before completion, or immediately when `callback_url` is set.
- `400`: Invalid request body
- `401`: Missing or invalid API key
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream source returned an error

---

[API](https://skmtc.dev/usecroma/apis/croma-marketplace-api.md) · [All operations](https://skmtc.dev/usecroma/apis/croma-marketplace-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usecroma/apis/croma-marketplace-api/revisions/df016cdb29d7?raw)