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

# Pair chips in bulk

> Pairs up to 100 chips to units of a single collection in one request. Units are issued in the order provided.



## OpenAPI

````yaml /openapi.json post /v1/chips/bulk
openapi: 3.1.0
info:
  title: Endstate API
  version: 0.1.0
  description: Endstate developer API for chip verification and ownership workflows.
servers:
  - url: https://api2.endstate.io
    description: Production
  - url: https://api-staging.endstate.io
    description: Staging
security: []
paths:
  /v1/chips/bulk:
    post:
      tags:
        - Chips
      summary: Pair chips in bulk
      description: >-
        Pairs up to 100 chips to units of a single collection in one request.
        Units are issued in the order provided.
      operationId: bulkPairChips
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 255
            description: >-
              Unique key that makes this request safe to retry. Replaying the
              key with the same body returns the original response with
              `Idempotent-Replayed: true`; replaying it with a different body
              returns 409 `idempotency.key_conflict`.
            example: a1b2c3d4-0000-4000-8000-000000000000
          required: false
          name: Idempotency-Key
          in: header
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateChipsBulkRequest'
            example:
              chips:
                - unit_id: 22222222-2222-2222-2222-222222222222
                  is_test: true
                - unit_id: 33333333-3333-3333-3333-333333333333
                  chip_id: ABCDEF0123
                  e: C78566198547116F3A715DC1C62AF96F
      responses:
        '201':
          description: Created chips, in the order provided.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateChipsBulkResponse'
              example:
                chips:
                  - chip_id: FEDCBA9876
                    is_test: true
                    unit:
                      id: 22222222-2222-2222-2222-222222222222
                      external_id: unit-001
                      name: Example Unit
                      attributes: null
                      created_at: '2026-05-16T12:00:00.000Z'
                      collection:
                        id: 8e1a7f50-90ab-4cde-8012-3456789abcde
                        name: Example Collection
                        external_id: collection-001
                        contract:
                          address: '0x1111111111111111111111111111111111111111'
                          chain_id: 84532
                          status: active
                        token:
                          status: pending
                          serial: null
                    scan_count: 0
                    created_at: '2026-05-16T12:00:00.000Z'
                  - chip_id: ABCDEF0123
                    is_test: false
                    unit:
                      id: 33333333-3333-3333-3333-333333333333
                      external_id: unit-002
                      name: Example Unit
                      attributes: null
                      created_at: '2026-05-16T12:00:00.000Z'
                      collection:
                        id: 8e1a7f50-90ab-4cde-8012-3456789abcde
                        name: Example Collection
                        external_id: collection-001
                        contract:
                          address: '0x1111111111111111111111111111111111111111'
                          chain_id: 84532
                          status: active
                        token:
                          status: pending
                          serial: null
                    scan_count: 0
                    created_at: '2026-05-16T12:00:00.000Z'
        '400':
          description: >-
            The request was malformed or failed validation.


            | Error code | When |

            | --- | --- |

            | `chip.bulk_mixed_collections` | A bulk pairing request included
            units from more than one collection. Pair one collection per
            request. |

            | `validation.failed` | The request failed schema validation. See
            `error.details` for per-field issues. |
          x-error-codes:
            - chip.bulk_mixed_collections
            - validation.failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                chip.bulk_mixed_collections:
                  summary: >-
                    A bulk pairing request included units from more than one
                    collection. Pair one collection per request.
                  value:
                    error:
                      code: chip.bulk_mixed_collections
                      message: >-
                        A bulk pairing request included units from more than one
                        collection. Pair one collection per request.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: >-
                        https://docs.endstate.io/errors/chip-bulk-mixed-collections
                validation.failed:
                  summary: >-
                    The request failed schema validation. See `error.details`
                    for per-field issues.
                  value:
                    error:
                      code: validation.failed
                      message: >-
                        The request failed schema validation. See
                        `error.details` for per-field issues.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/validation-failed
        '401':
          description: |-
            Authentication failed.

            | Error code | When |
            | --- | --- |
            | `auth.unauthorized` | Credential is missing or malformed. |
          x-error-codes:
            - auth.unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.unauthorized:
                  summary: Credential is missing or malformed.
                  value:
                    error:
                      code: auth.unauthorized
                      message: Credential is missing or malformed.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-unauthorized
        '403':
          description: >-
            Authenticated, but not permitted.


            | Error code | When |

            | --- | --- |

            | `auth.forbidden` | Credential is valid but does not have access to
            the requested resource or action. |
          x-error-codes:
            - auth.forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                auth.forbidden:
                  summary: >-
                    Credential is valid but does not have access to the
                    requested resource or action.
                  value:
                    error:
                      code: auth.forbidden
                      message: >-
                        Credential is valid but does not have access to the
                        requested resource or action.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/auth-forbidden
        '404':
          description: >-
            The resource does not exist within your organization.


            | Error code | When |

            | --- | --- |

            | `chip.not_found` | The chip ID does not exist in your
            organization. |

            | `unit.not_found` | The unit ID does not exist in your
            organization. |
          x-error-codes:
            - chip.not_found
            - unit.not_found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                chip.not_found:
                  summary: The chip ID does not exist in your organization.
                  value:
                    error:
                      code: chip.not_found
                      message: The chip ID does not exist in your organization.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/chip-not-found
                unit.not_found:
                  summary: The unit ID does not exist in your organization.
                  value:
                    error:
                      code: unit.not_found
                      message: The unit ID does not exist in your organization.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/unit-not-found
        '409':
          description: >-
            The request conflicts with the resource's current state.


            | Error code | When |

            | --- | --- |

            | `chip.already_paired` | The chip is already paired to a unit and
            cannot be paired again. |

            | `chip.bulk_pending` | A bulk pairing for this collection is still
            processing. Retry once it completes. |

            | `collection.not_active` | The collection has not finished
            provisioning. Wait until its status is `active`. |

            | `idempotency.in_progress` | A request with this `Idempotency-Key`
            is already in progress. |

            | `idempotency.key_conflict` | The `Idempotency-Key` was previously
            used with a different request body. |

            | `unit.issuance_pending` | One or more units already have an
            issuance in progress. Wait for it to settle. |
          x-error-codes:
            - chip.already_paired
            - chip.bulk_pending
            - collection.not_active
            - idempotency.in_progress
            - idempotency.key_conflict
            - unit.issuance_pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                chip.already_paired:
                  summary: >-
                    The chip is already paired to a unit and cannot be paired
                    again.
                  value:
                    error:
                      code: chip.already_paired
                      message: >-
                        The chip is already paired to a unit and cannot be
                        paired again.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/chip-already-paired
                chip.bulk_pending:
                  summary: >-
                    A bulk pairing for this collection is still processing.
                    Retry once it completes.
                  value:
                    error:
                      code: chip.bulk_pending
                      message: >-
                        A bulk pairing for this collection is still processing.
                        Retry once it completes.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/chip-bulk-pending
                collection.not_active:
                  summary: >-
                    The collection has not finished provisioning. Wait until its
                    status is `active`.
                  value:
                    error:
                      code: collection.not_active
                      message: >-
                        The collection has not finished provisioning. Wait until
                        its status is `active`.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/collection-not-active
                idempotency.in_progress:
                  summary: >-
                    A request with this `Idempotency-Key` is already in
                    progress.
                  value:
                    error:
                      code: idempotency.in_progress
                      message: >-
                        A request with this `Idempotency-Key` is already in
                        progress.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/idempotency-in-progress
                idempotency.key_conflict:
                  summary: >-
                    The `Idempotency-Key` was previously used with a different
                    request body.
                  value:
                    error:
                      code: idempotency.key_conflict
                      message: >-
                        The `Idempotency-Key` was previously used with a
                        different request body.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/idempotency-key-conflict
                unit.issuance_pending:
                  summary: >-
                    One or more units already have an issuance in progress. Wait
                    for it to settle.
                  value:
                    error:
                      code: unit.issuance_pending
                      message: >-
                        One or more units already have an issuance in progress.
                        Wait for it to settle.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/unit-issuance-pending
        '422':
          description: >-
            The request was well-formed but could not be processed.


            | Error code | When |

            | --- | --- |

            | `chip.invalid_e_value` | The tap credential (`e` value) was
            rejected as invalid. |
          x-error-codes:
            - chip.invalid_e_value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                chip.invalid_e_value:
                  summary: The tap credential (`e` value) was rejected as invalid.
                  value:
                    error:
                      code: chip.invalid_e_value
                      message: The tap credential (`e` value) was rejected as invalid.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/chip-invalid-e-value
        '500':
          description: >-
            Something went wrong on our end.


            | Error code | When |

            | --- | --- |

            | `internal.error` | An unexpected server error occurred. Retry with
            exponential backoff and include `request_id` in any support request.
            |
          x-error-codes:
            - internal.error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal.error:
                  summary: >-
                    An unexpected server error occurred. Retry with exponential
                    backoff and include `request_id` in any support request.
                  value:
                    error:
                      code: internal.error
                      message: >-
                        An unexpected server error occurred. Retry with
                        exponential backoff and include `request_id` in any
                        support request.
                      request_id: req_8e1a7f50-90ab-4cde-f012-3456789abcde
                      doc_url: https://docs.endstate.io/errors/internal-error
      security:
        - ApiKeyBearer: []
components:
  schemas:
    CreateChipsBulkRequest:
      type: object
      properties:
        chips:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  unit_id:
                    type: string
                    format: uuid
                    description: Unit (resource) the chip is paired to.
                    example: 11111111-1111-1111-1111-111111111111
                  is_test:
                    type: boolean
                    enum:
                      - true
                required:
                  - unit_id
                  - is_test
                additionalProperties: false
              - type: object
                properties:
                  unit_id:
                    type: string
                    format: uuid
                    description: Unit (resource) the chip is paired to.
                    example: 11111111-1111-1111-1111-111111111111
                  chip_id:
                    type: string
                    pattern: ^[0-9A-Fa-f]{10}$
                    description: >-
                      Chip identifier from the tap URL. Always returned
                      uppercase.
                    example: ABCDEF0123
                  e:
                    type: string
                    pattern: ^[0-9A-F]{32}$
                    description: PICC e-value from the tap URL.
                    example: C78566198547116F3A715DC1C62AF96F
                  c:
                    type: string
                    pattern: ^[0-9A-F]{16}$
                    description: >-
                      Tap verification code (`c`) from the tap URL. Include it
                      whenever the tag provides one.
                    example: 940E8AA6628759B3
                  is_test:
                    type: boolean
                    enum:
                      - false
                required:
                  - unit_id
                  - chip_id
                  - e
                additionalProperties: false
          minItems: 1
          maxItems: 100
      required:
        - chips
      description: >-
        Pair up to 100 chips in one request. All units must belong to the same
        collection; units are issued in the order provided.
    CreateChipsBulkResponse:
      type: object
      properties:
        chips:
          type: array
          items:
            $ref: '#/components/schemas/CreateChipResponse'
      required:
        - chips
      description: >-
        The paired chips, in the order provided. Each carries a snapshot of its
        unit and issuance status.
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              anyOf:
                - $ref: '#/components/schemas/ErrorCode'
                - type: string
              description: >-
                Stable, namespaced error code. The `ErrorCode` catalogue lists
                every code defined today; handle an unrecognized value as a
                generic failure rather than throwing, since codes are added over
                time.
              example: chip.not_found
            message:
              type: string
              description: >-
                Human-readable description, for logs and debugging. Wording may
                change without notice - never parse or match against it.
              example: Chip not found
            request_id:
              type: string
              description: >-
                Identifier for this request, matching the `X-Request-Id`
                response header. Log it and include it in any support request.
              example: req_8e1a7f50-90ab-4cde-f012-3456789abcde
            doc_url:
              type: string
              description: Documentation page for this error code.
              example: https://docs.endstate.io/errors/chip-not-found
            details:
              $ref: '#/components/schemas/ValidationErrorDetails'
          required:
            - code
            - message
            - request_id
            - doc_url
      required:
        - error
      description: >-
        Every error response, regardless of endpoint or HTTP status, uses this
        envelope.
    CreateChipResponse:
      type: object
      properties:
        chip_id:
          type: string
          pattern: ^[0-9A-F]{10}$
          description: Chip identifier from the tap URL.
          example: ABCDEF0123
        is_test:
          type: boolean
        unit:
          $ref: '#/components/schemas/ChipUnitSnapshot'
        scan_count:
          type: integer
          minimum: 0
        created_at:
          type: string
          format: date-time
      required:
        - chip_id
        - is_test
        - unit
        - scan_count
        - created_at
    ErrorCode:
      type: string
      enum:
        - validation.failed
        - auth.unauthorized
        - auth.forbidden
        - session_token.invalid_or_expired
        - session_token.wrong_chip
        - not_found.resource
        - rate_limit.exceeded
        - chip.not_found
        - chip.invalid_e_value
        - chip.already_scanned
        - quota.exceeded
        - chip.not_a_test_chip
        - unit.not_found
        - unit.already_exists
        - unit.not_minted
        - collection.not_found
        - collection.already_exists
        - collection.not_active
        - chip.already_paired
        - chip.bulk_mixed_collections
        - chip.bulk_pending
        - unit.issuance_pending
        - claim.owner_unknown
        - claim.already_to_recipient
        - claim.in_progress
        - claim.not_found
        - chip_replacement.locked
        - chip_replacement.in_progress
        - chip_replacement.not_found
        - transfer.owner_unknown
        - transfer.already_to_recipient
        - transfer.in_progress
        - transfer.not_found
        - idempotency.key_conflict
        - idempotency.in_progress
        - internal.error
      description: >-
        Stable, namespaced error code in `<resource>.<reason>` form. Branch on
        this rather than on `message` or the HTTP status. This is the catalogue
        as of this spec revision, not a closed set - see
        `ErrorResponse.error.code`.
      example: chip.not_found
    ValidationErrorDetails:
      type: object
      properties:
        formErrors:
          type: array
          items:
            type: string
          description: Issues that apply to the request as a whole rather than one field.
          example: []
        fieldErrors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Validation issues keyed by the field that failed.
          example:
            name:
              - Required
      required:
        - formErrors
        - fieldErrors
      description: Per-field validation detail. Present only on `validation.failed`.
    ChipUnitSnapshot:
      type: object
      properties:
        id:
          type: string
          format: uuid
        external_id:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        attributes:
          type:
            - object
            - 'null'
          additionalProperties: {}
        created_at:
          type: string
          format: date-time
        redirect_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Tap redirect URL for this unit; takes precedence over
            product/collection/org defaults.
          example: https://brand.example/p
        collection:
          $ref: '#/components/schemas/CollectionMembership'
      required:
        - id
        - external_id
        - name
        - attributes
        - created_at
        - redirect_url
        - collection
      description: >-
        Snapshot of the paired unit, including its collection and issuance
        status. Poll the unit (GET /v1/units/{unit_id}) until
        `collection.token.status` is `active`. Issuance has no failure status on
        this surface - if the unit stays `pending` well beyond a few minutes,
        stop polling and contact support.
    CollectionMembership:
      type:
        - object
        - 'null'
      properties:
        id:
          type: string
          format: uuid
        name:
          type:
            - string
            - 'null'
        external_id:
          type:
            - string
            - 'null'
        contract:
          type: object
          properties:
            address:
              type: string
              description: Unique address identifying the collection.
              example: '0x1111111111111111111111111111111111111111'
            chain_id:
              type: integer
              example: 84532
            status:
              type: string
              enum:
                - deploying
                - active
                - failed
              description: >-
                Collection lifecycle status. `deploying` while the collection is
                being provisioned; `active` once it is ready to use.
              example: active
          required:
            - address
            - chain_id
            - status
        token:
          $ref: '#/components/schemas/UnitToken'
      required:
        - id
        - name
        - external_id
        - contract
        - token
      description: >-
        The unit's collection. Null only for units created before collections
        existed.
    UnitToken:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - active
          description: >-
            Issuance state of this unit within the collection. `pending` until
            the unit is issued; `active` once issued. There is no failure
            status: a unit whose issuance cannot complete stays `pending` - if a
            unit remains `pending` well beyond a few minutes, stop polling and
            contact support.
          example: pending
        serial:
          type:
            - integer
            - 'null'
          description: >-
            Collection-scoped serial number. Assigned when the unit becomes
            `active`; null until then.
          example: 5
      required:
        - status
        - serial
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: end_sk
      description: >-
        Use `Authorization: Bearer end_sk_*` for partner API keys (e.g.
        `end_sk_AbCd_example_api_key`).

````