Identity methods

Create, update, and verify a customer identity, and upload identity documents, for Identity API integrations.

Use the identity methods to run KYC for Identity API integrations: capture the required customer data in your own UI, submit it through the SDK, and bring the customer to a verified state. The client handles authentication for you — no raw access token is required.

These identity methods are deprecated. Use the Customer API instead, which keys on customerId instead of a separate identity resource. Build new integrations against the Customer API, and migrate existing integrations before MoonPay removes these methods.

The six methods wrap the Identity API endpoints and follow the same Result pattern as the rest of the client:

Method	Endpoint	Purpose
createIdentity()	POST /platform/v1/identities	Create an identity for the connected customer.
getIdentity()	GET /platform/v1/identities/{id}	Fetch the identity, including its requirements.
updateIdentity()	PATCH /platform/v1/identities/{id}	Submit one or more outstanding requirements.
verifyIdentity()	POST /platform/v1/identities/{id}/verifications	Submit the identity for verification.
getIdentityUploadUrl()	POST /platform/v1/identities/{id}/files/upload-url	Issue a presigned URL for a document upload.
submitIdentityFiles()	POST /platform/v1/identities/{id}/files	Confirm previously uploaded documents.

The identity methods require an authenticated client. Run client.getConnection() with skipKyc: true first, and authenticate the customer with client.setupAuth() when the status is "connectionRequired".

For the field and document requirements by country, see KYC data requirements.

client.createIdentity()

createIdentity() is deprecated. Customers are created automatically now, so call getCustomer directly instead.

Create an identity for the connected customer. The response lists the requirements you need to fulfil before verification.

Create an identity

const result = await client.createIdentity({
  residentialAddress: { country: "USA" },
  capabilities: [{ product: "ramps" }],
});

if (!result.ok) {
  // Handle error
  console.error(result.error.code, result.error.message);
  return;
}

if (result.value.data === null) {
  // The customer is already onboarded — no outstanding requirements.
  return;
}

console.log(result.value.data.id, result.value.data.requirements);

createIdentity() parameters

Field	Type	Required	Description
residentialAddress.country	string	✅	The customer’s country of residence as an ISO 3166-1 alpha-3 code (for example, "USA").
capabilities	{ product: "ramps" }[]	✅	The capabilities to unlock for the customer. Must contain at least one entry.

createIdentity() result

Returns a Result<{ data: Identity | null }, DevPlatformApiError>. data is null (HTTP 204) when the customer has no outstanding requirements — they are already onboarded.

client.getIdentity()

getIdentity() is deprecated. Use getCustomer instead.

Fetch the identity, including the current status and requirement states.

Get an identity

const result = await client.getIdentity(identityId);

if (result.ok) {
  console.log(result.value.data.status, result.value.data.requirements);
}

getIdentity() parameters

Field	Type	Required	Description
id	string	✅	The identity identifier.

getIdentity() result

Returns a Result<{ data: Identity }, DevPlatformApiError>.

client.updateIdentity()

updateIdentity() is deprecated. Use submitCustomerKyc instead.

Submit one or more outstanding requirements on the identity. Each top-level field maps to a requirement category — submit the categories listed as incomplete in requirements.

Update an identity

const result = await client.updateIdentity(identityId, {
  basicDetails: {
    firstName: "Ada",
    lastName: "Lovelace",
    dateOfBirth: "1990-12-10",
  },
  residentialAddress: {
    street: "123 Main St",
    locality: "San Francisco",
    administrativeArea: "CA",
    postalCode: "94105",
    country: "USA",
  },
  phoneNumber: { number: "[phone]" },
});

updateIdentity() parameters

Field	Type	Required	Description
id	string	✅	The identity identifier.
basicDetails	object		The customer’s name, nationality, and date of birth (YYYY-MM-DD).
residentialAddress	object		The customer’s residential address. Country codes are ISO 3166-1 alpha-3.
phoneNumber	object		The customer’s phone number in E.164 format (for example, "[phone]").
taxIdentifiers	array		Tax identifiers: { type: "ssn" | "cpf", value } or { type: "tin", country, value }.

updateIdentity() result

Returns a Result<{ data: Identity }, DevPlatformApiError> reflecting the updated requirement states.

client.verifyIdentity()

verifyIdentity() is deprecated and has no direct replacement call. Customer API verification starts automatically once you submit the last outstanding requirement. See the Customer API guide for the flow.

Submit the identity for verification once all requirements are complete.

Verify an identity

const result = await client.verifyIdentity(identityId);

if (!result.ok) {
  // requirements_incomplete: submit the missing requirements first.
  console.error(result.error.code, result.error.message);
  return;
}

switch (result.value.data.status) {
  case "approved":
    // The customer is verified.
    break;
  case "processing":
    // Verification is running — poll getIdentity() for the outcome.
    break;
  case "challengeRequired":
    // Render the challenge frame with setupChallenge().
    console.log(result.value.data.challenge.url);
    break;
}

When the status is "challengeRequired", pass challenge.url to client.setupChallenge(). The challenge completes with flow: "identity" and the identityId.

verifyIdentity() parameters

Field	Type	Required	Description
id	string	✅	The identity identifier.

verifyIdentity() result

Returns a Result<{ data: IdentityVerificationResponse }, DevPlatformApiError>.

Field	Type	Required	Description
status	"approved" | "processing" | "challengeRequired"	✅	The verification outcome.
challenge	{ url: string; expiresAt: string }		Present when status is "challengeRequired". Pass url to setupChallenge().

client.getIdentityUploadUrl()

getIdentityUploadUrl() is deprecated. Use getCustomerUploadUrl instead. See Upload a file in the Customer API guide for the replacement flow.

Issue a presigned URL to upload an identity document. Upload the file with an HTTP PUT to the returned url, sending the returned headers.

Upload a document

const urlResult = await client.getIdentityUploadUrl(identityId, {
  fileType: "passport",
  mimeType: "image/jpeg",
});

if (!urlResult.ok) return;

const { uploadId, url, headers } = urlResult.value.data;

await fetch(url, {
  method: "PUT",
  headers,
  body: passportImageBlob,
});

getIdentityUploadUrl() parameters

Field	Type	Required	Description
id	string	✅	The identity identifier.
fileType	string	✅	One of "drivingLicence", "nationalIdentityCard", "passport", "residencePermit", "selfie", "proofOfAddress".
side	string		"front" or "back". Required for two-sided documents (drivingLicence, nationalIdentityCard, residencePermit); omit otherwise.
mimeType	string	✅	"image/jpeg", "image/png", or "application/pdf". Must match the Content-Type header you send on the upload request.

getIdentityUploadUrl() result

Returns a Result<{ data: IdentityFileUploadUrl }, DevPlatformApiError>.

Field	Type	Required	Description
uploadId	string	✅	The upload identifier to confirm with submitIdentityFiles().
url	string	✅	The presigned upload URL.
expiresAt	string	✅	An ISO 8601 timestamp for when the URL expires.
headers	object	✅	Headers to send on the upload request (Content-Type).

client.submitIdentityFiles()

submitIdentityFiles() is deprecated. Use submitCustomerFiles instead. See Upload a file in the Customer API guide for the replacement flow.

Confirm one or more uploaded documents so MoonPay processes them against the identity’s requirements.

Submit uploaded documents

const result = await client.submitIdentityFiles(identityId, {
  files: [{ uploadId, fileType: "passport" }],
});

if (result.ok) {
  console.log(result.value.data.requirements);
}

submitIdentityFiles() parameters

Field	Type	Required	Description
id	string	✅	The identity identifier.
files	array	✅	The uploads to confirm: { uploadId, fileType, side? }, matching the issued upload URLs.

submitIdentityFiles() result

Returns a Result<{ data: Identity }, DevPlatformApiError> reflecting the updated requirement states.

Shared types

Identity

Field	Type	Required	Description
id	string	✅	The identity identifier.
status	IdentityStatus	✅	The identity’s place in the KYC lifecycle.
capabilities	{ product: "ramps" }[]	✅	The capabilities requested for the customer.
requirements	Requirements	✅	Outstanding and completed requirements, keyed by category.
challenge	{ url: string; expiresAt: string }		Present only when status is "challengeRequired". Pass url to setupChallenge().
createdAt	string	✅	An ISO 8601 creation timestamp.
updatedAt	string	✅	An ISO 8601 last-update timestamp.

IdentityStatus

"created", "collecting", "verifying", "challengeRequired", "approved", "rejected", "manualReview", or "blocked".

Requirements

Each category is present when it applies to the customer’s jurisdiction, with a status of "incomplete" or "complete" and, for field-based categories, the requiredFields still outstanding.

Category	Fulfilled by
basicDetails	updateIdentity()
residentialAddress	updateIdentity()
phoneNumber	updateIdentity()
taxIdentifiers	updateIdentity()
identityDocuments	getIdentityUploadUrl() + submitIdentityFiles()
selfie	getIdentityUploadUrl() + submitIdentityFiles()
proofOfAddress	getIdentityUploadUrl() + submitIdentityFiles()

Errors

All identity methods return the standard MoonPay Platform API error shape, DevPlatformApiError, with code, message, and optional field-level errors. Notable codes: "requirements_incomplete" when verifying too early, "verification_rejected" on a terminal rejection, and "country_mismatch" when submitted data conflicts with the declared country.