Create an Entity

This guide walks you through registering a person and a company with Create an Entity. The entity is created without files. You upload them in the next step, Upload Documents and Proofs.

Prerequisites

A Stage access token. See Get Access Token.
The entity type: INDIVIDUAL for a natural person, COMPANY for a legal entity.
The identifying document. For a person: the tax ID (CPF, CUIT, RFC, CURP) or an identity document (DNI, PASSPORT, CC). For a company: the tax ID (CNPJ, CUIT, RFC, RUC, NIT). It becomes the primary document.
A stable externalId: your own reference, unique per merchant.
If Localpayment configured custom fields for your merchant, the schema. See Custom Fields.

Which documents to declare

A document is one id that holds as many files as you need, such as the front, back, and selfie of an identity document. Send the identifying document in document when you create the entity: it becomes the primary document. Declare every other document with Add a Document. The pair type + id must be unique in your merchant.

Type	Primary document	Other documents
INDIVIDUAL	Tax ID or identity document (CPF, DNI, PASSPORT). Proofs: FRONT, BACK, SELFIE.	PROOF_OF_ADDRESS, and any other evidence (PROOF_OF_FUNDS, PAYSLIP, OTHER).
COMPANY	Tax ID (CNPJ, CUIT, RFC, RUC, NIT). Proof: DOCUMENT.	ARTICLES_OF_INCORPORATION, PROOF_OF_ADDRESS. Owners are registered as INDIVIDUAL entities and linked with Manage UBOs.

The full list of values is in Document and Proof Types.

Minimum data

Type	Required by the API	Strongly recommended
INDIVIDUAL	externalId, type, name, lastname, document	birthdate, nationality, residenceCountry, email, phone, address
COMPANY	externalId, type, name, document	incorporationCountry, incorporationDate, legalRepresentativeName, website, email, phone, address

Missing required KYC data returns 422 INCOMPLETE_KYC_DATA.

Create a person

curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10" \
  -d '{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "birthdate": "1990-01-15",
    "nationality": "BRA",
    "birthCountry": "BRA",
    "residenceCountry": "BRA",
    "isPep": false,
    "email": "[email protected]",
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999990001"
    },
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310-100",
      "country": "BRA"
    },
    "document": {
      "type": "CPF",
      "id": "00000000000",
      "issuingCountry": "BRA"
    }
  }'

{
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INDIVIDUAL",
  "status": "PENDING_KYC",
  "name": "Jane",
  "lastname": "Doe",
  "birthdate": "1990-01-15",
  "gender": null,
  "nationality": "BRA",
  "birthCountry": "BRA",
  "residenceCountry": "BRA",
  "occupation": null,
  "isPep": false,
  "incorporationDate": null,
  "incorporationCountry": null,
  "website": null,
  "legalRepresentativeName": null,
  "email": "[email protected]",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990001"
  },
  "address": {
    "street": "Rua Exemplo",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "number": "123",
    "comment": null,
    "country": "BRA",
    "line2": null,
    "line3": null
  },
  "attributes": null,
  "documentationStatus": "NO_FILES",
  "document": {
    "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
    "entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "type": "CPF",
    "id": "00000000000",
    "issuingCountry": "BRA",
    "issueDate": null,
    "expirationDate": null,
    "isPrimary": true,
    "status": "PENDING",
    "metadata": null,
    "proofs": [],
    "createdAt": "2024-01-15T17:03:10Z",
    "updatedAt": "2024-01-15T17:03:10Z"
  },
  "documents": [],
  "version": 0,
  "createdAt": "2024-01-15T17:03:10Z",
  "updatedAt": "2024-01-15T17:03:10Z",
  "customFieldSchemaVersion": null
}

The response is 201 Created with the header ETag: "0".

Keep internalId (the entity) and document.documentId (the primary document). The next steps need both.

Create a company

A company with its tax ID as primary document, an address with additional lines, and custom fields:

{
  "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "COMPANY",
  "name": "Example Company S.A.",
  "incorporationCountry": "BRA",
  "incorporationDate": "2020-01-15",
  "website": "https://www.example.com",
  "email": "[email protected]",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990000"
  },
  "legalRepresentativeName": "Jane Doe",
  "isPep": false,
  "address": {
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "country": "BRA",
    "line2": "Sala 100",
    "line3": "Torre A"
  },
  "document": {
    "type": "CNPJ",
    "id": "00000000000100",
    "issuingCountry": "BRA"
  },
  "attributes": {
    "reasonForAccountOpening": "receive_payments_for_goods_and_services",
    "sourceOfFundsAndIncome": "sales_of_goods_and_services",
    "numberOfEmployees": "11-50",
    "estimatedAnnualRevenueUsd": "1m_to_10m",
    "estimatedMonthlyVolumeUsd": "50000",
    "businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
    "countryTaxResidence": "BRA",
    "socialMedia": "https://www.linkedin.com/company/example",
    "emailPixKey": "[email protected]"
  }
}

Handle errors in your integration

import os
import uuid
import requests

BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]

payload = {
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "document": {"type": "CPF", "id": "00000000000", "issuingCountry": "BRA"},
}

response = requests.post(
    f"{BASE_URL}/v1/entities",
    json=payload,
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Correlation-ID": str(uuid.uuid4()),
    },
    timeout=30,
)

if response.status_code == 201:
    entity = response.json()
    entity_id = entity["internalId"]
    primary_document_id = entity["document"]["documentId"]
else:
    problem = response.json()  # application/problem+json
    code = problem.get("code")
    if code == "DUPLICATE_ENTITY":
        # Already registered: look it up with GET /v1/entities?externalId=...
        pass
    elif code in ("VALIDATION_ERROR", "CUSTOM_FIELDS_INVALID"):
        for detail in problem.get("details", []):
            print(f"{detail['field']}: {detail['issue']}")
    else:
        # Quote the correlation id when you contact support
        print(f"{response.status_code} {code} correlationId={problem.get('correlationId')}")

Common errors

Error	Cause	Fix
400 VALIDATION_ERROR	Unknown property, two-letter country code, a documents list instead of document, or no document.	Check the field named in each entry of details. Move extra data to attributes.
400 CUSTOM_FIELDS_INVALID	attributes does not satisfy the custom-fields schema.	Read the schema and fix the field named in details.
409 DUPLICATE_ENTITY	externalId, or a document type + id, is already used in your merchant.	Reuse the existing entity. Find it with List Entities.
422 INCOMPLETE_KYC_DATA	Minimum KYC data is missing.	Add name and lastname (person) or name (company).

Example of a custom-fields validation error:

{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}

⚠️
A tax ID (CPF, CNPJ, CUIT, RFC) is a document, not a field of the entity. Send it in document. Country codes must be ISO 3166-1 alpha-3 (BRA, not BR).

Next steps

Upload Documents and Proofs

Attach the files that support each declared document.

Create an Entity reference

All request fields, response fields, and error codes.