> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Create claim > Initiate a portability or ownership claim to take control of a Pix key currently registered to another account. The claim status will initially be "OPEN" and must go through a confirmation process. The key status for the claimer will typically be 4 (IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST). ## OpenAPI ````yaml en/openapi/v3-current/pix.yaml POST /v1/claims openapi: 3.0.3 info: title: Plugin BR Pix Direct - Complete API description: | Complete API for Brazilian Pix instant payment system including Pix key dictionary operations, QR code generation/decoding, transactions and transaction limits. version: 1.0.0 servers: - url: https://plugin-pix-direct.api.lerian.net - url: https://plugin-pix-direct-qrcode.api.lerian.net security: - bearerAuth: [] paths: /v1/claims: post: tags: - Key Claims API summary: Create claim description: > Initiate a portability or ownership claim to take control of a Pix key currently registered to another account. The claim status will initially be "OPEN" and must go through a confirmation process. The key status for the claimer will typically be 4 (IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateClaimRequest' responses: '200': description: Claim created successfully content: application/json: schema: $ref: '#/components/schemas/ClaimResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' components: schemas: CreateClaimRequest: type: object required: - key - accountId properties: key: type: string description: Pix key to claim. example: '12345678901' accountId: type: string format: uuid description: Account identifier of the claimer. example: 019c96a0-0ac0-7de9-9f53-9cf842a2ee5a ClaimResponse: type: object required: - key - type - status - claimId - statusDescription properties: key: type: string description: Pix key value. example: '+5511987654321' type: $ref: '#/components/schemas/KeyTypeEnum' status: $ref: '#/components/schemas/KeyStatusEnum' claimId: type: string description: Unique identifier for the claim. example: claim_abc123xyz statusDescription: type: string description: Human-readable claim status description. example: OPEN KeyTypeEnum: type: integer description: > Pix key type identifier. Numeric codes that specify the type of Pix key being used. **Valid values:** - `0` = CPF (Individual taxpayer ID with 11 digits, e.g., "12345678901") - `1` = CNPJ (Company taxpayer ID with 14 digits, e.g., "12345678000190") - `2` = EMAIL (Email address, e.g., "user@example.com") - `3` = PHONE (Phone number in international format, e.g., "+5511987654321") - `4` = EVP (Random UUID key automatically generated, e.g., "123e4567-e89b-12d3-a456-426614174000") enum: - 0 - 1 - 2 - 3 - 4 x-enum-varnames: - CPF - CNPJ - EMAIL - PHONE - EVP example: 3 KeyStatusEnum: type: integer description: > Pix key registration status code. Indicates the current state of a Pix key in its lifecycle. **Valid values:** - `-1` = CANCELLED (Key registration was cancelled) - `0` = FINALIZED (Key is finalized/pending confirmation) - `1` = ACTIVE (Key is active and operational) - `2` = WAITING_OWNERSHIP_CONFIRMATION (Awaiting ownership confirmation from the user) - `3` = CREATING (Key is being created in the system) - `4` = IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST (I am claimer, pending claim confirmation) - `5` = IM_CLAIMER_PENDING_OWNER_GIVEWAY (I am claimer, awaiting current owner to release the key) - `6` = IM_OWNER_PENDING_GIVEAWAY_CONFIRM (I am owner, pending approval to transfer key) - `7` = IM_CLAIMER_AND_OWNER_GAVEAWAY_PENDING_MY_CONFIRM (Transfer initiated, awaiting my confirmation) enum: - -1 - 0 - 1 - 2 - 3 - 4 - 5 - 6 - 7 x-enum-varnames: - CANCELLED - FINALIZED - ACTIVE - WAITING_OWNERSHIP_CONFIRMATION - CREATING - IM_CLAIMER_PENDING_CONFIRM_CLAIM_REQUEST - IM_CLAIMER_PENDING_OWNER_GIVEWAY - IM_OWNER_PENDING_GIVEAWAY_CONFIRM - IM_CLAIMER_AND_OWNER_GAVEAWAY_PENDING_MY_CONFIRM example: 1 ErrorResponse: type: object properties: code: type: string description: Error code message: type: string description: Error message details: type: array items: type: string description: Additional error details responses: BadRequest: description: Bad Request - Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_key_type: summary: Invalid key type value: code: INVALID_KEY_TYPE message: Key type must be between 0 and 4 details: - 'keyType: must be one of [0, 1, 2, 3, 4]' missing_required_field: summary: Missing required field value: code: VALIDATION_ERROR message: Required field is missing details: - 'accountId: field is required' invalid_document_format: summary: Invalid document format value: code: INVALID_DOCUMENT message: Document must be valid CPF (11 digits) or CNPJ (14 digits) details: - 'document: must match pattern ^\d{11}$|^\d{14}$' invalid_phone_format: summary: Invalid phone format value: code: INVALID_PHONE message: Phone must be in Brazilian format details: - 'phone: must match pattern ^\+55\d{2}\d{8,9}$' Unauthorized: description: Unauthorized - Invalid or missing authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missing_token: summary: Missing authentication token value: code: MISSING_TOKEN message: Authorization header is required details: [] invalid_token: summary: Invalid token value: code: INVALID_TOKEN message: Invalid or expired access token details: [] expired_token: summary: Expired token value: code: TOKEN_EXPIRED message: Access token has expired. Please obtain a new token. details: [] InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: generic_error: summary: Generic internal error value: code: INTERNAL_ERROR message: An internal error occurred. Please try again later. details: [] database_error: summary: Database error value: code: DATABASE_ERROR message: Database operation failed details: [] external_service_error: summary: External service error value: code: EXTERNAL_SERVICE_ERROR message: External service (JD Pix) is temporarily unavailable details: [] securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > JWT Bearer token authentication. Obtain token from `/v1/login/oauth/access_token` endpoint using client credentials (clientId and clientSecret). Include token in Authorization header: `Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` Token expires after 3600 seconds (1 hour). ````