Create customer

post

https://sandbox-api-gtw.softpoint.io/api/{version}/customers

This API is used to create a customer and link it to a location.

It returns the customer. Its id is our customer_id: store it with your user and use it in the payment method, transaction and transfer endpoints, and as customer_id in gateway sales and tokenizations.

Note: If a customer with the same customer_id_external, email or phone (checked in that order) already exists in your locations, it is returned with created: false and status 200, and linked to the location, instead of creating a duplicate. Status 201 means it was created.

URL

{{interface_url}}/{{version}}/customers

Method

POST

Headers

Authorization: Bearer {access_token} (or Api-Key)

Request Parameters

Field	Type	Required	Description
first_name	String	Yes	Max 64.
last_name	String	Yes	Max 64.
email	String	Conditional	Required if `phone` is not sent. Valid email, max 64.
phone	String	Conditional	Required if `email` is not sent. 7-15 digits, no symbols.
phone_country_id	Integer	Conditional	Required with `phone`. `3` = United States.
customer_id_external	String	No	Your own customer ID. Max 45. Recommended: avoids duplicates and lets you search by it.
gender	Integer	No	`0` not set, `1` male, `2` female.
citizenship	String	No	Max 20.
address.line1	String	No	Street. Max 64.
address.line2	String	No	Apartment / suite. Max 64.
address.city	String	No	Max 64.
address.zipcode	String	No	Max 64.
address.state_id	Integer	No	SoftPoint state ID.
address.country_id	Integer	No	SoftPoint country ID. `3` = United States.
location_id	Integer	Conditional	Location to use. Required when the token covers more than one location (corporate / sub corporate); with a location token it is taken from the token.

URL Parameters

None.

Example Request (cURL)

curl --location --request POST '{{interface_url}}/{{version}}/customers' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{access_token}}' \
--data '{
  "location_id": 279685,
  "first_name": "Ana",
  "last_name": "Garcia",
  "email": "[email protected]",
  "phone": "5125550134",
  "phone_country_id": 3,
  "customer_id_external": "CRM-1001",
  "gender": 2,
  "address": {
    "line1": "100 Main St",
    "line2": null,
    "city": "Austin",
    "zipcode": "78701"
  }
}'

Example Response (JSON) — 200

{
  "id": 48213,
  "customer_id_external": "CRM-1001",
  "first_name": "Ana",
  "last_name": "Garcia",
  "email": "[email protected]",
  "phone": "5125550134",
  "phone_country_id": 3,
  "gender": 2,
  "citizenship": null,
  "address": {
    "line1": "100 Main St",
    "line2": null,
    "city": "Austin",
    "zipcode": "78701",
    "state_id": null,
    "country_id": 3
  },
  "email_verified_at": null,
  "phone_verified_at": null,
  "status": "active",
  "editable": true,
  "locations": [
    {
      "location_id": 279685,
      "name": "Main Street",
      "linked_at": "2026-11-05T18:16:18Z"
    }
  ],
  "payment_methods_count": {
    "card": 1,
    "ach": 0
  },
  "created_at": "2026-11-05T18:16:18Z",
  "updated_at": "2026-11-05T18:16:18Z",
  "created": true
}

Error Responses

Format: { "error": { "code", "name", "message", "details" } }

Status	Error	When
400	missing_required_parameters	Missing or invalid field (see `error.details`) or `location_id` missing.
400	customer_contact_required	Send `email` or `phone`.
422	invalid_parameter_value	`customer_id_external` and `id_external` sent with different values.
403	developer_scope_forbidden	`location_id` outside your scope.

Response

200OK