Skip to main content

​
Customers API

Customers represent end users in your application. Each customer is linked via an externalUserId that you provide.

​
Create Customer

Create a new customer or retrieve an existing one by externalUserId.

​
Endpoint

POST /v1/customers

​
Request Body

ParameterTypeRequiredDescription
externalUserIdstringYesYour unique identifier for this user
emailstringNoCustomer email address
metadataobjectNoCustom key-value data

​
Example Request

curl -X POST https://api.nowramp.com/v1/customers \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user_123",
    "email": "[email protected]",
    "metadata": {
      "plan": "premium"
    }
  }'

​
Response

{
  "success": true,
  "data": {
    "id": "cust_abc123",
    "externalUserId": "user_123",
    "email": "[email protected]",
    "kycStatus": "pending",
    "metadata": {
      "plan": "premium"
    },
    "createdAt": "2024-01-15T10:00:00Z",
    "updatedAt": "2024-01-15T10:00:00Z"
  }
}

​
Get Customer

Retrieve a customer by ID.

​
Endpoint

GET /v1/customers/{customerId}

​
Example Request

curl https://api.nowramp.com/v1/customers/cust_abc123 \
  -H "X-API-Key: your_api_key"

​
Get Customer by External ID

Retrieve a customer using your external user ID.

​
Endpoint

GET /v1/customers/external/{externalUserId}

​
Example Request

curl https://api.nowramp.com/v1/customers/external/user_123 \
  -H "X-API-Key: your_api_key"

​
Update Customer

Update customer information.

​
Endpoint

PATCH /v1/customers/{customerId}

​
Request Body

ParameterTypeDescription
emailstringUpdated email address
metadataobjectUpdated metadata (merged with existing)

​
Example Request

curl -X PATCH https://api.nowramp.com/v1/customers/cust_abc123 \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "plan": "enterprise"
    }
  }'

​
List Customers

List customers for your project.

​
Endpoint

GET /v1/customers

​
Query Parameters

ParameterTypeDescription
kycStatusstringFilter by KYC status
limitnumberMax results (default: 20)
cursorstringPagination cursor

​
Example Request

curl "https://api.nowramp.com/v1/customers?kycStatus=approved&limit=10" \
  -H "X-API-Key: your_api_key"

​
KYC Statuses

StatusDescription
pendingKYC not started
in_progressKYC verification in progress
approvedKYC approved
rejectedKYC rejected
expiredKYC verification expired

​
Customer Lifecycle

                    ┌─────────────┐
                    │   Create    │
                    │  Customer   │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   pending   │
                    │    (KYC)    │
                    └──────┬──────┘
                           │
                    Start KYC Flow
                           │
                           ▼
                    ┌─────────────┐
                    │ in_progress │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │ approved │ │ rejected │ │ expired  │
       └──────────┘ └──────────┘ └──────────┘