Create User

curl -X POST https://services-staging.getplu.com/api/v2/partner/card/users \
  -H "Authorization: Bearer sk_staging_your_api_key" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+14155555555",
    "accountPurpose": "personal use",
    "ipAddress": "203.0.113.42",
    "isTermsOfServiceAccepted": true,
    "program": "custodial",
    "address": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  }'

const response = await fetch(
  'https://services-staging.getplu.com/api/v2/partner/card/users',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_staging_your_api_key',
      'Content-Type': 'application/json',
      'idempotency-key': '550e8400-e29b-41d4-a716-446655440000',
    },
    body: JSON.stringify({
      firstName: 'Jane',
      lastName: 'Doe',
      email: '[email protected]',
      phoneNumber: '+14155555555',
      accountPurpose: 'personal use',
      ipAddress: '203.0.113.42',
      isTermsOfServiceAccepted: true,
      program: 'custodial',
      address: '123 Main Street',
      city: 'San Francisco',
      region: 'CA',
      postalCode: '94105',
      countryCode: 'US',
    }),
  }
);

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "serviceId": "acme-user-abc123def456ghi",
    "verificationUrl": "https://withpersona.com/verify?inquiry-id=inq_abc123..."
  }
}

{
  "status": "error",
  "message": "DUP_USER",
  "data": {
    "error": "User already exists with this email"
  }
}

{
  "status": "error",
  "message": "INSUFFICIENT_WALLET_BALANCE",
  "data": {
    "error": "Partner wallet has insufficient funds for KYC fee"
  }
}

POST

partner

card

users

curl -X POST https://services-staging.getplu.com/api/v2/partner/card/users \
  -H "Authorization: Bearer sk_staging_your_api_key" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+14155555555",
    "accountPurpose": "personal use",
    "ipAddress": "203.0.113.42",
    "isTermsOfServiceAccepted": true,
    "program": "custodial",
    "address": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  }'

const response = await fetch(
  'https://services-staging.getplu.com/api/v2/partner/card/users',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_staging_your_api_key',
      'Content-Type': 'application/json',
      'idempotency-key': '550e8400-e29b-41d4-a716-446655440000',
    },
    body: JSON.stringify({
      firstName: 'Jane',
      lastName: 'Doe',
      email: '[email protected]',
      phoneNumber: '+14155555555',
      accountPurpose: 'personal use',
      ipAddress: '203.0.113.42',
      isTermsOfServiceAccepted: true,
      program: 'custodial',
      address: '123 Main Street',
      city: 'San Francisco',
      region: 'CA',
      postalCode: '94105',
      countryCode: 'US',
    }),
  }
);

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "serviceId": "acme-user-abc123def456ghi",
    "verificationUrl": "https://withpersona.com/verify?inquiry-id=inq_abc123..."
  }
}

{
  "status": "error",
  "message": "DUP_USER",
  "data": {
    "error": "User already exists with this email"
  }
}

{
  "status": "error",
  "message": "INSUFFICIENT_WALLET_BALANCE",
  "data": {
    "error": "Partner wallet has insufficient funds for KYC fee"
  }
}

Creates a new user and initiates KYC verification through Persona. Returns a verificationUrl where the user completes identity verification. This is the v2 flow using Persona for KYC — it requires fewer fields than the legacy v1 endpoint and provides a smoother verification experience.

string

required

Bearer token. Example: Bearer sk_staging_your_api_key

string

required

Unique key to prevent duplicate user creation. Use a UUID.

string

required

User’s first name. 1-100 characters.

string

required

User’s last name. 1-100 characters.

string

required

User’s email address. Must be unique across your partner account.

string

required

International phone number. Example: +14155555555

string

required

Purpose of the account. 1-200 characters. Example: personal use, business expenses.

string

required

User’s IP address at the time of registration.

boolean

required

Must be true. Confirms the user has accepted the terms of service.

string

required

Card program type. Either custodial or non_custodial.

string

Ethereum wallet address. Required if program is non_custodial.

string

HTTPS URL to redirect the user after Persona verification. Overrides the default redirect URL set in your profile.

string

required

User’s street address. 1-500 characters. Example: 123 Main Street.

string

required

User’s city. 1-100 characters.

string

required

User’s state or region. 1-100 characters. Example: CA, Lagos.

string

required

User’s postal/zip code. 1-20 characters.

string

required

ISO 3166-1 alpha-2 country code of the user’s country of residence. Example: US, KE, NG.

curl -X POST https://services-staging.getplu.com/api/v2/partner/card/users \
  -H "Authorization: Bearer sk_staging_your_api_key" \
  -H "Content-Type: application/json" \
  -H "idempotency-key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "[email protected]",
    "phoneNumber": "+14155555555",
    "accountPurpose": "personal use",
    "ipAddress": "203.0.113.42",
    "isTermsOfServiceAccepted": true,
    "program": "custodial",
    "address": "123 Main Street",
    "city": "San Francisco",
    "region": "CA",
    "postalCode": "94105",
    "countryCode": "US"
  }'

const response = await fetch(
  'https://services-staging.getplu.com/api/v2/partner/card/users',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_staging_your_api_key',
      'Content-Type': 'application/json',
      'idempotency-key': '550e8400-e29b-41d4-a716-446655440000',
    },
    body: JSON.stringify({
      firstName: 'Jane',
      lastName: 'Doe',
      email: '[email protected]',
      phoneNumber: '+14155555555',
      accountPurpose: 'personal use',
      ipAddress: '203.0.113.42',
      isTermsOfServiceAccepted: true,
      program: 'custodial',
      address: '123 Main Street',
      city: 'San Francisco',
      region: 'CA',
      postalCode: '94105',
      countryCode: 'US',
    }),
  }
);

{
  "status": "success",
  "message": "User created successfully",
  "data": {
    "serviceId": "acme-user-abc123def456ghi",
    "verificationUrl": "https://withpersona.com/verify?inquiry-id=inq_abc123..."
  }
}

{
  "status": "error",
  "message": "DUP_USER",
  "data": {
    "error": "User already exists with this email"
  }
}

{
  "status": "error",
  "message": "INSUFFICIENT_WALLET_BALANCE",
  "data": {
    "error": "Partner wallet has insufficient funds for KYC fee"
  }
}

After User Creation

Redirect the user to the verificationUrl to complete Persona KYC
After verification, the user is redirected to your configured redirect URL with ?referenceId={serviceId}
Listen for KYC webhook events to know when the user is approved
Once approved (user.kyc.approved), you can create a card for the user

Sandbox Testing

In the staging environment, you can control the KYC outcome by appending a keyword to the user’s lastName field. This lets you test each scenario without going through real identity verification.

Keyword in `lastName`	KYC Outcome	Example `lastName`
`Approved`	KYC approved — user can create cards	`DoeApproved`
`Denied`	KYC denied	`DoeDenied`
`needsVerification`	Additional verification required	`DoeneedsVerification`

The keyword is case-sensitive and must be appended to the end of the last name with no spaces or separators.

Example Webhook Payloads

Approved

{
  "event": "user.kyc-event",
  "timestamp": "2026-02-19T20:49:29.927Z",
  "data": {
    "serviceId": "acme-user-7mFQc5aCslAWtkd",
    "status": "approved",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "DoeApproved"
  }
}

Denied

{
  "event": "user.kyc-event",
  "timestamp": "2026-02-19T21:01:49.217Z",
  "data": {
    "serviceId": "acme-user-yvDaVMdFaug51H4",
    "status": "denied",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "DoeDenied",
    "reason": "WRONG_USER_REGION, REGULATIONS_VIOLATIONS"
  }
}

Needs Verification

{
  "event": "user.kyc-event",
  "timestamp": "2026-02-19T21:02:49.083Z",
  "data": {
    "serviceId": "acme-user-G9KZgnhgbndDdJg",
    "status": "needsVerification",
    "email": "[email protected]",
    "firstName": "Jane",
    "lastName": "DoeneedsVerification",
    "verificationLink": "https://kyc.getplu.com/verify?userId=e5508685-2771-48fd-8cbc-c8c3e6df9179"
  }
}

verificationLink is only present on needsVerification events. reason is only present on denied events and contains one or more comma-separated denial codes.

Profile

Wallet

Withdrawals

Users

Cards

Transactions

After User Creation

Sandbox Testing

Example Webhook Payloads

​After User Creation

​Sandbox Testing

​Example Webhook Payloads

After User Creation

Sandbox Testing

Example Webhook Payloads