Customers

Create or update an array of 1 to 100 customers atomically. If any item fails, none are stored. customer.code, customer.type, and customer.name are required when creating a new customer. Surname and description are optional. Phones, emails, and addresses are optional; phone.value, email.value, and address.city are required when supplied for a new customer. New contacts and addresses are appended; omitted existing contact data is not deleted.

POSThttp://localhost:3000/api/v1/customers
Method
POST
Content type
application/json
Authentication
Required · active locations · non-expired key
Maximum payload
1 MiB
Request frequency
30 requests per 60 seconds

Request headers

Send these headers with every POST request.

Content-Type: application/json
Authorization: Bearer y3m_ABCD2345_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To get the authorization key, open Dashboard, use the three-dot menu on the company card, and select API integrations. Under Secret keys, select Create secret key, enable the Customers scope, and assign at least one active location. Copy the full key when it is created because it is shown only once, then send it after Bearer in the Authorization header.

Request fields

Required and optional fields accepted in the JSON request body. Unknown fields are rejected at every level.

FieldTypeRequirementDescription
externalIdstringRequiredCaller-controlled Customer identifier from the source system; it does not need to be a UUID. It is unique within the company; the internal Y3M identifier is a UUID v7. Maximum 200 characters.
customerobject | nullOptionalOptional customer identity. Name is required here when creating a new customer.
customer.codestringOptionalOptional visible customer code. Maximum 100 characters.
customer.typestringOptionalOptional external customer type. Maximum 100 characters.
customer.namestringOn createRequired when externalId does not match an existing customer. When omitted for an existing customer, the stored name is used. Maximum 200 characters.
customer.surnamestring | nullOptionalOptional customer surname. Maximum 100 characters.
descriptionstring | nullOptionalOptional customer description. Maximum 2,000 characters.
phonesarrayOptionalUp to 20 phone entries appended when not already stored for this customer. The first new phone in the payload becomes the default.
phones[].valuestringOn createRequired when adding a phone to a new customer. Up to 100 characters.
phones[].positionintegerOptionalOptional positive display position.
emailsarrayOptionalUp to 20 email entries appended when not already stored for this customer. The first new email in the payload becomes the default.
emails[].valuestringOn createRequired when adding an email to a new customer. Up to 320 characters.
emails[].positionintegerOptionalOptional positive display position.
addressesarrayOptionalUp to 20 addresses to append when identical addresses do not already exist. The first new address in the payload becomes the default.
addresses[].countryCodestring | nullOptionalOptional ISO 3166-1 alpha-2 country code using two uppercase letters. View country codes
addresses[].regionstring | nullOptionalOptional region or state.
addresses[].postalCodestring | nullOptionalOptional postal code.
addresses[].citystringOn createRequired for an address on a new customer; maximum 150 characters.
addresses[].streetstring | nullOptionalOptional street or complete free-form address.
addresses[].buildingstring | nullOptionalOptional building number or name.
addresses[].unitstring | nullOptionalOptional apartment, office, or unit.
addresses[].positionintegerOptionalOptional positive display position. Positions must be unique within the addresses array.

Error responses

Possible errors returned by this endpoint and how to resolve them.

StatusCodeMeaningResolution
400INVALID_JSONThe request body is not valid JSON.Send one correctly formatted JSON array.
400INVALID_PAYLOADThe JSON body is not an array.Send a root JSON array containing between 1 and 100 objects.
401UNAUTHORIZEDThe Authorization header is missing, malformed, or contains an invalid API key.Send a valid API key using the Bearer authorization scheme.
401API_KEY_EXPIREDThe API key has reached its expiration date.Create a new API key and retry the request.
403FORBIDDENThe API key cannot access this module or is not assigned to an active company location.Assign an active location, enable the required module, or use another key.
409CUSTOMER_DELETEDA customer referenced by externalId is deleted.Restore the customer in Y3M, then retry the request.
413PAYLOAD_TOO_LARGEThe request body exceeds the 1 MiB limit.Reduce the JSON payload size to 1 MiB or less.
415UNSUPPORTED_MEDIA_TYPEThe Content-Type header is not application/json.Send Content-Type: application/json.
422VALIDATION_ERRORThe JSON is valid but one or more fields do not satisfy the endpoint contract.Use each { path, message } entry in error.details to correct the specified field.
429RATE_LIMIT_EXCEEDEDMore than 30 requests were sent within 60 seconds.Wait for the number of seconds specified by the Retry-After header.
500INTERNAL_ERRORRequest infrastructure, authentication, or rate-limit processing is temporarily unavailable.Retry later. Contact support if the error continues.
500STORAGE_ERRORThe validated payload could not be stored.Retry later. Contact support if the error continues.

Example request

Send this JSON array in the POST request body.

[
  {
    "externalId": "CUSTOMER-123",
    "customer": {
      "code": "CUSTOMER-001",
      "type": "Wholesale",
      "name": "Example",
      "surname": "Company"
    },
    "description": "Wholesale customer",
    "phones": [
      {
        "value": "+32470000000",
        "position": 1
      }
    ],
    "emails": [
      {
        "value": "orders@example.com",
        "position": 1
      }
    ],
    "addresses": [
      {
        "countryCode": "BE",
        "region": "Brussels-Capital",
        "postalCode": "1000",
        "city": "Brussels",
        "street": "Example Street",
        "building": "1",
        "unit": "12",
        "position": 1
      }
    ]
  }
]