> This page is for North America.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://trustly.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://trustly.ferndocs.com/_mcp/server.

# Create or Update a Customer

POST https://sandbox.trustly.one/api/v1/customers
Content-Type: application/json

Creates a new customer record in the merchant account. In cases when the customer was not created at the time an Authorization was established, use this endpoint to register customer details, such as name, email, and optional metadata, to support your integration.

If an existing `customerId` or `externalId` is provided, the specified customer will be updated with any new or updated properties. To remove properties of an existing customer, set the property to `null`. Before using this endpoint, it may be helpful to call [Get Customer by ID](ref:get-customers-customerid) to obtain the relevant customer object.

Reference: https://trustly.ferndocs.com/api-reference/api/customers/post-customers

## Authentication

- `Authorization` header (basic auth, required) — Basic authentication of the form `Basic <base64(username:password)>`.

## Request

### Query parameters

- `externalId` (string, optional) — The externalId that was passed when the Customer record was created.

### Body (application/json)

This endpoint expects a Customer.

- `name` (string, required) — Full name of the Customer
- `address` (Address, required) — Valid mailing or billing address associated with the customer
- `phone` (string, required) — Customer phone number.
- `email` (string, required) — Customer email address.
- `taxId` (string, optional) — Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*
- `dateOfBirth` (string, optional) — Customer date of birth.
- `createdAt` (integer, optional) — The record created date and time as a UNIX timestamp.
- `updatedAt` (integer, optional) — The record created date and time as a UNIX timestamp.
- `customerId` (string, optional) — A unique Trustly customer identifier.
- `externalId` (string, optional) — A unique merchant customer identifier.
- `merchantId` (string, optional) — A unique Trustly merchant identifier.
- `enrollDate` (integer, optional) — Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp.
- `vip` (string, optional) — Range that determines how low-risk the customer represents to the merchant
- `currency` (string, optional) — Customer currency.
- `balance` (string, optional) — Customer account balance (not associated with a financial institution account).
- `organizationNumber` (string, optional) — Organization number for business accounts
- `externalTier` (string, optional) — It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.)
- `personId` (string, optional) — Unique customer identity throughout different banks.
- `customData` (CustomerCustomData, optional) — Object for sending merchant-specific custom data.
- `driverLicense` (DriverLicense, optional)
- `nationalId` (string, optional) — Customer National ID

## Response

### 200

OK

- `customer` (Customer, optional) — The Trustly customer object, containing identification details and contact information.

## Types

### Address

Valid mailing or billing address associated with the customer

- `country` (string, required) — 2 character [ISO Country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
- `address1` (string, optional) — Address line 1 (e.g., street or PO Box)
- `address2` (string, optional) — Address line 2 (e.g., apartment, suite or unit number)
- `city` (string, optional) — City, district, town or village
- `state` (string, optional) — State, province or region code
- `zip` (string, optional) — ZIP or Postal Code

### CustomerCustomData

Object for sending merchant-specific custom data.

### DriverLicense

- `number` (string, required) — Driver License number.
- `state` (string, required) — 2 character ISO State code.

### Customer

The Trustly customer object, containing identification details and contact information.

- `name` (string, required) — Full name of the Customer
- `address` (Address, required) — Valid mailing or billing address associated with the customer
- `phone` (string, required) — Customer phone number.
- `email` (string, required) — Customer email address.
- `taxId` (string, optional) — Customer tax ID (e.g. SSN [US], SIN [CA]). *May be required depending on industry and location.*
- `dateOfBirth` (string, optional) — Customer date of birth.
- `createdAt` (integer, optional) — The record created date and time as a UNIX timestamp.
- `updatedAt` (integer, optional) — The record created date and time as a UNIX timestamp.
- `customerId` (string, optional) — A unique Trustly customer identifier.
- `externalId` (string, optional) — A unique merchant customer identifier.
- `merchantId` (string, optional) — A unique Trustly merchant identifier.
- `enrollDate` (integer, optional) — Date of the user's first transaction in your system, regardless of payment method used as a UNIX timestamp.
- `vip` (string, optional) — Range that determines how low-risk the customer represents to the merchant
- `currency` (string, optional) — Customer currency.
- `balance` (string, optional) — Customer account balance (not associated with a financial institution account).
- `organizationNumber` (string, optional) — Organization number for business accounts
- `externalTier` (string, optional) — It should describe the customer''s rank to the merchant (e.g. Gold, Diamond, 4 stars, etc.)
- `personId` (string, optional) — Unique customer identity throughout different banks.
- `customData` (CustomerCustomData, optional) — Object for sending merchant-specific custom data.
- `driverLicense` (DriverLicense, optional)
- `nationalId` (string, optional) — Customer National ID

## Examples

**Request**

```json
{
  "name": "Joe User",
  "address": {
    "country": "US",
    "address1": "2000 Broadway St",
    "city": "Redwood City",
    "state": "CA",
    "zip": "94063"
  },
  "phone": "+16505551212",
  "email": "joe.user@mail.com",
  "taxId": "012345678",
  "createdAt": 1555696836548,
  "updatedAt": 1555696836548,
  "customerId": "1002580963",
  "externalId": "4567890",
  "merchantId": "1002463580",
  "enrollDate": 1555696836548,
  "driverLicense": {
    "number": "A1234567",
    "state": "CA"
  }
}
```

**Response**

```json
{
  "customer": {
    "name": "Joe User",
    "address": {
      "country": "US",
      "address1": "2000 Broadway St",
      "city": "Redwood City",
      "state": "CA",
      "zip": "94063"
    },
    "phone": "+16505551212",
    "email": "joe.user@mail.com",
    "taxId": "012345678",
    "createdAt": 1555696836548,
    "updatedAt": 1555696836548,
    "customerId": "1002580963",
    "externalId": "4567890",
    "merchantId": "1002463580",
    "enrollDate": 1555696836548,
    "driverLicense": {
      "number": "A1234567",
      "state": "CA"
    }
  }
}
```

**SDK Code**

```python Example
import requests

url = "https://sandbox.trustly.one/api/v1/customers"

payload = {
    "name": "Joe User",
    "address": {
        "country": "US",
        "address1": "2000 Broadway St",
        "city": "Redwood City",
        "state": "CA",
        "zip": "94063"
    },
    "phone": "+16505551212",
    "email": "joe.user@mail.com",
    "taxId": "012345678",
    "createdAt": 1555696836548,
    "updatedAt": 1555696836548,
    "customerId": "1002580963",
    "externalId": "4567890",
    "merchantId": "1002463580",
    "enrollDate": 1555696836548,
    "driverLicense": {
        "number": "A1234567",
        "state": "CA"
    }
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<username>", "<password>"))

print(response.json())
```

```javascript Example
const url = 'https://sandbox.trustly.one/api/v1/customers';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{"name":"Joe User","address":{"country":"US","address1":"2000 Broadway St","city":"Redwood City","state":"CA","zip":"94063"},"phone":"+16505551212","email":"joe.user@mail.com","taxId":"012345678","createdAt":1555696836548,"updatedAt":1555696836548,"customerId":"1002580963","externalId":"4567890","merchantId":"1002463580","enrollDate":1555696836548,"driverLicense":{"number":"A1234567","state":"CA"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://sandbox.trustly.one/api/v1/customers"

	payload := strings.NewReader("{\n  \"name\": \"Joe User\",\n  \"address\": {\n    \"country\": \"US\",\n    \"address1\": \"2000 Broadway St\",\n    \"city\": \"Redwood City\",\n    \"state\": \"CA\",\n    \"zip\": \"94063\"\n  },\n  \"phone\": \"+16505551212\",\n  \"email\": \"joe.user@mail.com\",\n  \"taxId\": \"012345678\",\n  \"createdAt\": 1555696836548,\n  \"updatedAt\": 1555696836548,\n  \"customerId\": \"1002580963\",\n  \"externalId\": \"4567890\",\n  \"merchantId\": \"1002463580\",\n  \"enrollDate\": 1555696836548,\n  \"driverLicense\": {\n    \"number\": \"A1234567\",\n    \"state\": \"CA\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.SetBasicAuth("<username>", "<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Example
require 'uri'
require 'net/http'

url = URI("https://sandbox.trustly.one/api/v1/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Joe User\",\n  \"address\": {\n    \"country\": \"US\",\n    \"address1\": \"2000 Broadway St\",\n    \"city\": \"Redwood City\",\n    \"state\": \"CA\",\n    \"zip\": \"94063\"\n  },\n  \"phone\": \"+16505551212\",\n  \"email\": \"joe.user@mail.com\",\n  \"taxId\": \"012345678\",\n  \"createdAt\": 1555696836548,\n  \"updatedAt\": 1555696836548,\n  \"customerId\": \"1002580963\",\n  \"externalId\": \"4567890\",\n  \"merchantId\": \"1002463580\",\n  \"enrollDate\": 1555696836548,\n  \"driverLicense\": {\n    \"number\": \"A1234567\",\n    \"state\": \"CA\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://sandbox.trustly.one/api/v1/customers")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Joe User\",\n  \"address\": {\n    \"country\": \"US\",\n    \"address1\": \"2000 Broadway St\",\n    \"city\": \"Redwood City\",\n    \"state\": \"CA\",\n    \"zip\": \"94063\"\n  },\n  \"phone\": \"+16505551212\",\n  \"email\": \"joe.user@mail.com\",\n  \"taxId\": \"012345678\",\n  \"createdAt\": 1555696836548,\n  \"updatedAt\": 1555696836548,\n  \"customerId\": \"1002580963\",\n  \"externalId\": \"4567890\",\n  \"merchantId\": \"1002463580\",\n  \"enrollDate\": 1555696836548,\n  \"driverLicense\": {\n    \"number\": \"A1234567\",\n    \"state\": \"CA\"\n  }\n}")
  .asString();
```

```php Example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://sandbox.trustly.one/api/v1/customers', [
  'body' => '{
  "name": "Joe User",
  "address": {
    "country": "US",
    "address1": "2000 Broadway St",
    "city": "Redwood City",
    "state": "CA",
    "zip": "94063"
  },
  "phone": "+16505551212",
  "email": "joe.user@mail.com",
  "taxId": "012345678",
  "createdAt": 1555696836548,
  "updatedAt": 1555696836548,
  "customerId": "1002580963",
  "externalId": "4567890",
  "merchantId": "1002463580",
  "enrollDate": 1555696836548,
  "driverLicense": {
    "number": "A1234567",
    "state": "CA"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp Example
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://sandbox.trustly.one/api/v1/customers");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"Joe User\",\n  \"address\": {\n    \"country\": \"US\",\n    \"address1\": \"2000 Broadway St\",\n    \"city\": \"Redwood City\",\n    \"state\": \"CA\",\n    \"zip\": \"94063\"\n  },\n  \"phone\": \"+16505551212\",\n  \"email\": \"joe.user@mail.com\",\n  \"taxId\": \"012345678\",\n  \"createdAt\": 1555696836548,\n  \"updatedAt\": 1555696836548,\n  \"customerId\": \"1002580963\",\n  \"externalId\": \"4567890\",\n  \"merchantId\": \"1002463580\",\n  \"enrollDate\": 1555696836548,\n  \"driverLicense\": {\n    \"number\": \"A1234567\",\n    \"state\": \"CA\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Example
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "Joe User",
  "address": [
    "country": "US",
    "address1": "2000 Broadway St",
    "city": "Redwood City",
    "state": "CA",
    "zip": "94063"
  ],
  "phone": "+16505551212",
  "email": "joe.user@mail.com",
  "taxId": "012345678",
  "createdAt": 1555696836548,
  "updatedAt": 1555696836548,
  "customerId": "1002580963",
  "externalId": "4567890",
  "merchantId": "1002463580",
  "enrollDate": 1555696836548,
  "driverLicense": [
    "number": "A1234567",
    "state": "CA"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.trustly.one/api/v1/customers")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```