Entity Statuses and Error Codes

Reference tables for the Entities API: lifecycle statuses, derived statuses, the error format, and the catalog of error codes.

Entity status

%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    S((Start)) --> PK[PENDING_KYC]
    PK --- L0(["Request Verification"]):::lbl --> IR[IN_REVIEW]
    IR --> PK
    IR --> AC[ACTIVE]
    IR --> RJ[REJECTED]
    AC --> BL[BLOCKED]
    BL --> AC
    PK --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((End))
    class S,E terminal
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px

Status	Meaning	Set by
PENDING_KYC	Created and awaiting files, or returned for a correction (reason in statusReason).	You (creation). Localpayment Compliance (correction).
IN_REVIEW	Under review by Localpayment. Data, documents, files, and UBO links are frozen.	You, with Request Verification
ACTIVE	Approved.	Localpayment Compliance
REJECTED	Review failed. Reason in the status history.	Localpayment Compliance
BLOCKED	Temporarily blocked. Reason in the status history.	Localpayment Compliance
CLOSED	Logically deleted. Final.	You (Close an Entity)

You make the creation, IN_REVIEW (with Request Verification), and CLOSED; every other transition is made by Localpayment. IN_REVIEW entities reject edits to data, documents, files, and UBO links with 409 ENTITY_IN_REVIEW. REJECTED, BLOCKED, and CLOSED entities reject edits, new documents, and uploads with 409 ENTITY_NOT_EDITABLE.

Document status (derived)

Status	Rule
PENDING	No approved file yet, or a file is awaiting review.
VERIFIED	At least one active proof, and all of them APPROVED.
REJECTED	At least one active proof REJECTED.
EXPIRED	expirationDate is in the past. Takes precedence over the other statuses.

Proof review status (verificationStatus)

Status	Meaning
PENDING	Uploaded, not yet reviewed.
IN_REVIEW	A Localpayment reviewer opened it.
APPROVED	Accepted. Final for that file.
REJECTED	Refused. See verificationReason. Replace the file by uploading the same proofType once the entity is not IN_REVIEW.

Proof lifecycle (status)

Status	Meaning
CURRENT	The active file of its proofType on the document.
SUPERSEDED	Replaced by a newer upload of the same FRONT, BACK, or SELFIE.
DELETED	Removed with Delete a Proof. Kept for audit.

Documentation coverage (documentationStatus)

Value	Meaning
NO_FILES	No document has a file.
PARTIAL	Some documents have files.
COMPLETE	Every document has at least one file. Does not imply approval.

Error format

Errors follow RFC 9457 (application/problem+json). code is a stable machine-readable string, details names the offending field when applicable, and correlationId identifies the request: quote it when you contact support.

{
  "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 conflict without field details:

{
  "type": "about:blank",
  "title": "Conflict",
  "status": 409,
  "detail": "Conflict",
  "instance": "/api/entity/v1/entities/7c9e6679-7425-40de-944b-e07fc1f90ae7/ubos",
  "code": "UBO_ALREADY_LINKED",
  "correlationId": "acdfa68b-e1da-4764-84df-0a1e949d0939",
  "details": []
}

Branch on code, not on title or detail: only code is guaranteed to stay stable.

Error codes

HTTP	code	Cause
400	CUSTOM_FIELDS_INVALID	attributes does not satisfy your custom-fields schema. details[] lists field and issue.
400	MISSING_OR_INVALID_CLIENT_CODE	Your merchant account could not be identified from the request. Check the credentials you are using.
400	VALIDATION_ERROR	A field, header, path or query parameter is missing, unknown or invalid. details[] lists field and issue.
401	MISSING_OR_INVALID_ACTOR	The access token does not identify the user performing the action.
401	UNAUTHORIZED	Missing or invalid access token.
403	TENANT_MISMATCH	The request mixes identifiers of two merchant accounts. Check the credentials you are using.
404	CLIENT_NOT_FOUND	The merchant account in your credentials does not exist in Localpayment.
404	CUSTOM_FIELD_SCHEMA_NOT_FOUND	No custom-fields schema is published for your merchant.
404	DOCUMENT_NOT_FOUND	The document does not exist, was deleted, or belongs to another merchant.
404	ENTITY_NOT_FOUND	The entity does not exist or belongs to another merchant.
404	PROOF_NOT_FOUND	The proof does not exist or belongs to another merchant.
404	UBO_NOT_FOUND	The UBO link does not exist, has already ended, or belongs to another merchant.
409	CONCURRENT_MODIFICATION	Two uploads of the same proofType on the same document happened at the same time. Retry the request.
409	DUPLICATE_ENTITY	externalId, or the pair type + id of a document, already exists in your merchant.
409	ENTITY_IN_REVIEW	The entity is IN_REVIEW: its data, documents, files, and UBO links are frozen until Localpayment Compliance resolves it.
409	ENTITY_NOT_EDITABLE	The entity is REJECTED, BLOCKED or CLOSED, or the operation would remove the primary document or the only document.
409	INVALID_STATUS_TRANSITION	The entity is not in a status that allows this operation (for example, an entity that is already CLOSED).
409	PROOF_APPROVED	The proof is APPROVED: it cannot be replaced or deleted.
409	PROOF_SUPERSEDED	The proof was replaced by a newer upload of the same proofType on the same document. Only the active proof is reviewed.
409	UBO_ALREADY_LINKED	The person already has an active UBO link with this company.
409	UBO_LIMIT_EXCEEDED	The company already has 50 active UBO links.
412	VERSION_CONFLICT	If-Match does not match the current entity version. Read the entity again and retry.
413	FILE_TOO_LARGE	The uploaded file exceeds 10 MB.
413	PAYLOAD_TOO_LARGE	attributes exceeds 64 KB.
415	UNSUPPORTED_FILE_TYPE	The uploaded file is not a JPG, PNG or PDF.
415	UNSUPPORTED_MEDIA_TYPE	The request Content-Type is not the one the endpoint expects (application/json, or multipart/form-data for uploads).
422	ENTITY_NOT_ACTIVE	The company (or the person) is CLOSED, BLOCKED or REJECTED.
422	INCOMPLETE_KYC_DATA	Minimum KYC data is missing: name and lastname for INDIVIDUAL, name for COMPANY.
422	INVALID_CONTROL_ROLE	controlRole is not one of the role codes listed in Link a UBO. Codes are case-sensitive: director returns this error.
422	INVALID_ENTITY_TYPE	companyId must be a COMPANY and personId an INDIVIDUAL.
422	INVALID_PERCENTAGE	ownershipPercentage is outside 0 to 100 or has more than two decimals.
422	INVALID_VALIDITY_RANGE	validTo is earlier than validFrom.
422	NO_PROOFS_UPLOADED	The entity has no uploaded files. Upload at least one file before requesting verification.
502	STORAGE_WRITE_FAILED	The file could not be stored. Retry the upload.
503	CLIENT_DIRECTORY_UNAVAILABLE	Localpayment could not resolve your merchant account at this moment. Retry later.

Errors about your merchant account (MISSING_OR_INVALID_CLIENT_CODE, CLIENT_NOT_FOUND, TENANT_MISMATCH, MISSING_OR_INVALID_ACTOR, CLIENT_DIRECTORY_UNAVAILABLE) come from the credentials in your access token, not from the request body. Check that you use the access token of the right merchant account, and contact support with the correlationId if the error persists.