> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SIGEP II Person

> Read one person's hoja de vida in Colombia's SIGEP II directory by the `servant_id` from SIGEP II People Search: current post, entity and office, contact details, place of birth, education, work history, contracts in force with their object and value, and the entity's salary scale. Asked hojas de vida are kept and served from Croma's copy for 7 days (`checked_at`, `served_from`). Returns `found: false` when the id is not in the directory.

**Lookup endpoint**: answers from Croma's copy when it holds a recent answer for the key, otherwise reads the source and keeps the answer; carries `checked_at` and `served_from`.



## OpenAPI

````yaml /api-reference/openapi.json post /co/sigep/servant/v1
openapi: 3.1.0
info:
  title: Croma Marketplace API
  version: 1.0.0
  description: >-
    Government-data APIs for Colombia, Peru, Mexico, United States, Brazil, El
    Salvador, Bolivia, Japan, Chile, Venezuela, and Guatemala, plus global web
    search. Croma normalizes public-sector data into structured JSON for product
    teams and AI agents.


    Every operation is a POST with a JSON body and an organization API key as a
    bearer token; every operation is an idempotent lookup and accepts an
    optional `Idempotency-Key` header. Paths carry their major version (`/v1`);
    the versioning and deprecation policy, including the `Deprecation` and
    `Sunset` headers a retiring endpoint sends, is at
    https://docs.usecroma.com/versioning. Rate limits are per organization and
    reported on every response (`RateLimit-Policy`, `X-RateLimit-*`):
    https://docs.usecroma.com/rate-limits.
  termsOfService: https://usecroma.com/en/terms
  contact:
    name: Croma support
    url: https://usecroma.com/en/support
    email: support@usecroma.com
servers:
  - url: https://api.croma.run
security: []
paths:
  /co/sigep/servant/v1:
    post:
      tags:
        - Colombia
        - SIGEP II
      summary: SIGEP II Person
      description: >-
        Read one person's hoja de vida in Colombia's SIGEP II directory by the
        `servant_id` from SIGEP II People Search: current post, entity and
        office, contact details, place of birth, education, work history,
        contracts in force with their object and value, and the entity's salary
        scale. Asked hojas de vida are kept and served from Croma's copy for 7
        days (`checked_at`, `served_from`). Returns `found: false` when the id
        is not in the directory.


        **Lookup endpoint**: answers from Croma's copy when it holds a recent
        answer for the key, otherwise reads the source and keeps the answer;
        carries `checked_at` and `served_from`.
      operationId: sigep_servant
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - servant_id
              properties:
                servant_id:
                  type: string
                  pattern: ^[A-Za-z]\d{1,12}-\d{1,8}-\d{1,3}$
                  description: >-
                    The `id` of a person from the people search, e.g.
                    `S2060152-4395-4`.
              additionalProperties: false
            example:
              servant_id: S2060152-4395-4
      responses:
        '200':
          description: Successful response
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            X-Cache:
              $ref: '#/components/headers/X-Cache'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SigepServantResponse'
        '400':
          description: Invalid request body
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: Missing or invalid API key
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '429':
          description: Rate limit exceeded
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '500':
          description: Internal error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '502':
          description: Upstream source returned an error
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
      externalDocs:
        description: Interactive documentation and examples
        url: https://docs.usecroma.com/guides/colombia/sigep
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional client-chosen key for this request (any string up to 255
        characters, e.g. a UUID). Every Croma operation is an idempotent lookup:
        repeating a request with the same body returns the same result and
        creates nothing, so retrying after a timeout or network failure is
        always safe. The key is echoed back in the `Idempotency-Key` response
        header so you can correlate a retry with its first attempt. Each attempt
        that reaches the API counts against the rate limit.
      schema:
        type: string
        maxLength: 255
        example: 0f8e9a42-6b7c-4d1e-9a3f-2c5d7e8f9a0b
  headers:
    X-Request-Id:
      description: Unique id for the request (req_…). Include it in support reports.
      schema:
        type: string
    RateLimit-Policy:
      description: >-
        Quota policy for this endpoint as an IETF RateLimit-Policy structured
        field, e.g. `"default";q=100;w=86400` (100 requests per 86400-second
        window per organization). Endpoints with an extra hourly ceiling list
        both policies, e.g. `"webSearch";q=100;w=3600, "default";q=100;w=86400`.
        Present on every response, including 401 and 429.
      schema:
        type: string
        example: '"default";q=100;w=86400'
    Idempotency-Key:
      description: >-
        The `Idempotency-Key` the request carried, echoed back unchanged. Absent
        when the request sent none.
      schema:
        type: string
    Deprecation:
      description: >-
        Present only on an endpoint version scheduled for removal: the date the
        deprecation took effect (RFC 9745). A `Sunset` header and a `Link` with
        `rel="successor-version"` accompany it. Policy:
        https://docs.usecroma.com/versioning
      schema:
        type: string
        example: '@1767225600'
    Sunset:
      description: >-
        Present only on an endpoint version scheduled for removal: the date
        after which it answers 410 (RFC 8594). Announced in the changelog at
        least 90 days ahead.
      schema:
        type: string
        format: date-time
        example: Wed, 01 Apr 2026 00:00:00 GMT
    X-RateLimit-Limit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests left before you are throttled.
      schema:
        type: integer
    X-RateLimit-Reset:
      description: ISO 8601 timestamp when the window resets.
      schema:
        type: string
        format: date-time
    X-Cache:
      description: >-
        HIT or MISS. Cached hits spend no credits, but still count toward an
        hourly ceiling.
      schema:
        type: string
        enum:
          - HIT
          - MISS
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  schemas:
    SigepServantResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/SigepServantData'
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
          properties:
            type:
              type: string
              description: >-
                Broad category: invalid_request_error, authentication_error,
                not_found_error, rate_limit_error, upstream_error, api_error.
            code:
              type: string
              description: Machine-readable specific code.
            message:
              type: string
              description: Human-readable explanation, safe to surface in UI.
            param:
              type: string
              description: Field that triggered the error. Present on validation errors.
            details:
              type: object
              description: Free-form structured detail.
    SigepServantData:
      type: object
      properties:
        found:
          type: boolean
          description: false when the directory has no hoja de vida under this id.
        servant_id:
          type: string
        checked_at:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            When the directory was last read for this hoja de vida (ISO
            timestamp).
        served_from:
          type: string
          enum:
            - copy
            - upstream
            - stale
          description: >-
            `copy`: Croma's stored copy, still fresh; `upstream`: read from the
            directory just now; `stale`: the directory could not be read, so the
            last stored copy is served.
        servant:
          anyOf:
            - type: object
              properties:
                id:
                  type: string
                full_name:
                  type: string
                position:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Current post.
                employment_type:
                  anyOf:
                    - type: string
                      enum:
                        - servidor_publico
                        - contratista
                    - type: 'null'
                  description: >-
                    `servidor_publico` (on the payroll) or `contratista`
                    (contractor); null when the directory does not say.
                entity:
                  anyOf:
                    - type: string
                    - type: 'null'
                dependency:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Office or unit inside the entity.
                email:
                  anyOf:
                    - type: string
                    - type: 'null'
                phone:
                  anyOf:
                    - type: string
                    - type: 'null'
                fax:
                  anyOf:
                    - type: string
                    - type: 'null'
                birthplace:
                  anyOf:
                    - type: object
                      properties:
                        municipality:
                          anyOf:
                            - type: string
                            - type: 'null'
                        department:
                          anyOf:
                            - type: string
                            - type: 'null'
                        country:
                          anyOf:
                            - type: string
                            - type: 'null'
                      required:
                        - municipality
                        - department
                        - country
                    - type: 'null'
                  description: Municipality of birth; null when not reported.
                education:
                  type: array
                  items:
                    type: object
                    properties:
                      level:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Level, e.g. "PROFESIONAL", "ESPECIALIZACION", "ONCE"
                          (secondary school).
                      program:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: >-
                          Programme or title, e.g. "DERECHO"; null when "NO
                          APLICA".
                      status:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: e.g. "Graduado".
                      raw:
                        type: string
                        description: The line as the directory prints it.
                    required:
                      - level
                      - program
                      - status
                      - raw
                experience:
                  type: array
                  items:
                    type: object
                    properties:
                      position:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Post held.
                      entity:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Employer (public entity or private company).
                      start_date:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: yyyy-mm-dd.
                      end_date:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: yyyy-mm-dd; null while current.
                      current:
                        type: boolean
                        description: true when the directory marks the post as current.
                    required:
                      - position
                      - entity
                      - start_date
                      - end_date
                      - current
                contracts:
                  type: array
                  items:
                    type: object
                    properties:
                      entity:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Contracting entity.
                      object:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Object of the contract.
                      start_date:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: yyyy-mm-dd.
                      end_date:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: yyyy-mm-dd.
                      amount:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: Contract value in COP.
                      amount_text:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: The value as printed, e.g. "$21.620.000,00".
                    required:
                      - entity
                      - object
                      - start_date
                      - end_date
                      - amount
                      - amount_text
                  description: Contracts in force (contractors).
                salary_scale_entity:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: Entity whose salary scale `salary_scale` lists.
                salary_scale:
                  type: array
                  items:
                    type: object
                    properties:
                      level:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Hierarchical level, e.g. "ASESOR", "PROFESIONAL".
                      denomination:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Name of the post.
                      grade:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: Salary grade, e.g. "01"; null when "No aplica".
                      total:
                        anyOf:
                          - type: number
                          - type: 'null'
                        description: Monthly amount in COP.
                      total_text:
                        anyOf:
                          - type: string
                          - type: 'null'
                        description: The amount as printed.
                    required:
                      - level
                      - denomination
                      - grade
                      - total
                      - total_text
                  description: >-
                    Salary scale of the entity, by level, denomination and grade
                    (servants).
                url:
                  type: string
                  description: The person's page in the public directory.
              required:
                - id
                - full_name
                - position
                - employment_type
                - entity
                - dependency
                - email
                - phone
                - fax
                - birthplace
                - education
                - experience
                - contracts
                - salary_scale_entity
                - salary_scale
                - url
            - type: 'null'
      required:
        - found
        - servant_id
        - checked_at
        - served_from
        - servant
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Use Authorization: Bearer YOUR_API_KEY'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.