Add Customer

Creates a new customer with the provided details. Returns the newly created customer object with system-generated IDs and default balances.

Endpoint

POST/v2/customer

Link

Gateway APIstagep.tst-apidmndelss.com

Request

Headers

Key	Value	Required
Authorization	Bearer <JWT>	Yes
Content-Type	application/json	Yes
Accept	application/json	Yes

Request Body (JSON)

Field	Type	Description & Requirements	Required	Example
name	string	First name (individual) or Company name (corporate).	Yes	"John" or "Acme Inc."
lastname	string	Last name (individuals only).	No	"Doe"
comment	string	Internal notes/comments.	No	"VIP client"
company	string	Company name (if corporate).	No	"Acme Corporation"
type	string	Customer type: - CORPORATE: Business entity - INDIVIDUAL: Person	No	"INDIVIDUAL"

Example Request Body (Individual):

json

{
  "name": "John",
  "lastname": "Doe",
  "type": "INDIVIDUAL",
  "comment": "Premium customer"
}

Example Request Body (Corporate):

json

{
  "name": "Acme Inc.",
  "company": "Acme Corporation",
  "type": "CORPORATE",
  "comment": "Business account"
}

---

Response (200 OK)

Returns the created customer object with system-generated fields.

Response Fields

Field	Type	Description	Example
cuid	string	System-generated customer ID.	"DqCsgSE-4e95-ViYbNI"
puid	string	Partner/user ID.	"127c9ea7-3ea7-4063-9fa4-c69e796c55e4"
status	string	Initial status: NEW.	"NEW"
createAt	string	Creation timestamp (ISO 8601).	"2024-05-20T10:30:00Z"
updateAt	string	Update timestamp (ISO 8601).	"2024-05-20T10:30:00Z"
name	string	Name from request.	"John"
lastname	string	Last name from request.	"Doe"
comment	string	Comment from request.	"Premium customer"
company	string	Company name from request.	""
type	string	Customer type from request.	"INDIVIDUAL"
balance	object	Initial balance (0, in default currency).	-
balanceHold	object	Initial held balance (0).	-

Money Object (for balances)

Field	Type	Description	Example
currencyCode	string	Currency code.	"USD"
units	string	Whole units.	"0"
nanos	integer	Fractional units.	0

Example Response:

json

{
  "item": {
    "cuid": "DqCsgSE-4e95-ViYbNI",
    "puid": "127c9ea7-3ea7-4063-9fa4-c69e796c55e4",
    "status": "NEW",
    "createAt": "2024-05-20T10:30:00Z",
    "updateAt": "2024-05-20T10:30:00Z",
    "name": "John",
    "lastname": "Doe",
    "comment": "Premium customer",
    "company": "",
    "type": "INDIVIDUAL",
    "balance": {
      "currencyCode": "USD",
      "units": "0",
      "nanos": 0
    },
    "balanceHold": {
      "currencyCode": "USD",
      "units": "0",
      "nanos": 0
    }
  }
}

---

Examples

Request (Corporate Customer)

bash

curl -X POST 'https://stagep.tst-apidmndelss.com/v2/customer' \
  -H 'Authorization: Bearer eyJhbGci...wNLGA' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Tech Solutions Ltd",
    "company": "Tech Solutions Group",
    "type": "CORPORATE",
    "comment": "Enterprise client"
  }'

---

Error Responses

1. Missing Required Field:

   json

   { "error": "name is required" }

2. Invalid Type:

   json

   { "error": "Invalid type: INVALID_TYPE" }

3. Duplicate Customer:

   json

   { "error": "Customer already exists" }

---

Notes

• Default Values:

  • status defaults to NEW
  • type defaults to CORPORATE if not specified
  • Balances initialize to 0 in system default currency
• Next Steps:

  • New customers typically require verification (MODERATED → ACCEPTED)
  • Add accounts via /v2/account endpoint

Real request Example

Authorization:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOjE2NCwiZXhwIjoxNzYxMTMxMTE2LCJrZXkiOiI1Y2ZiOGZjN2RmYjk4ZjVkYmIyZTgwNTVkZWFhN2U2Zjk4MzEyYmE3Iiwib3RwX3ZlcmlmaWVkIjpmYWxzZX0.ns5XvumhlZ6NNxMy6ubfBEhpiRw6_QxODCfnyNEyc_Q
{
  "name": "API",
  "lastname": "Testing",
  "comment": "string",
  "company": "API Testing",
  "type": "CORPORATE"
}
{
  "name": "API",
  "lastname": "Testing",
  "comment": "string",
  "company": "API Testing",
  "type": "CORPORATE"
}

Real response example

200 OK

{
  "item": {
    "customerId": "Dsmwr6E-x1oN-B3KfkJ4D53SA",
    "partnerId": "3354815d-1a23-4b1c-81ec-306388cddfa4",
    "status": "NEW",
    "createAt": "2025-10-22T11:00:26Z",
    "updateAt": "2025-10-22T11:00:26Z",
    "name": "API",
    "lastname": "Testing",
    "comment": "string",
    "company": "API",
    "type": "CORPORATE",
    "balance": null,
    "balanceHold": null
  }
}