Store New Customer

Create the Azotte-side projection of a customer using identity data sourced from your system. Returns the canonical AzotteCustomer record (including CustomerUrn).

Endpoint

POST/api/c2a/customer/store

Request Parameters

Body: StoreCustomerRequest.

customerCustomerDto

required

Customer payload.

See CustomerDto

claimedRegionClaimedRegion

required

Country / language context claimed by the caller. Scopes storefront, currency, tax.

See ClaimedRegion

CustomerDto

externalIdentifierstring

required

Tenant-side identifier. Must be unique per tenant.

emailstring

Customer email.

phoneNumberstring

E.164 phone number.

salutationstring

Salutation prefix.

firstNamestring

Given name.

lastNamestring

Family name.

genderEnGender

Gender code.

Values:FemaleMaleOtherUnspecified

See EnGender

legalTypeEnPersonLegalType

Legal classification of the customer.

Values:IndividualCorporate

See EnPersonLegalType

primaryBillingAddressPostalAddress

Billing address.

See PostalAddress

corporationInfoCorporationInfo

Conditional. Required when legalType = Corporate.

See CorporationInfo

privacyAzotteCustomerPrivacySettings

Communication consents.

See AzotteCustomerPrivacySettings

statusstring

Caller-asserted status.

ClaimedRegion

countryCodestring

required

ISO 3166-1 alpha-2 country code.

languageCodestring

required

ISO 639-1 language code.

Request Example

{
  "customer": {
    "externalIdentifier": "crm-9981273",
    "email": "jane.doe@example.com",
    "phoneNumber": "+49 170 1234567",
    "salutation": "Ms.",
    "firstName": "Jane",
    "lastName": "Doe",
    "gender": "Female",
    "legalType": "Individual",
    "primaryBillingAddress": {
      "street": "Hauptstr. 1",
      "city": "Berlin",
      "postalCode": "10115",
      "countryCode": "DE"
    }
  },
  "claimedRegion": {
    "countryCode": "DE",
    "languageCode": "de"
  }
}

Response Parameters

StoreCustomerResponse.

resultAzotteCustomer

Canonical customer record.

See AzotteCustomer

result.customerUrnstring

Azotte-assigned URN. Use this in every downstream call.

result.externalIdentifierstring

Echo of supplied ExternalId.

result.emailstring

Echoed email.

result.statusstring

Operational status (Active, etc.).

statusAzotteStatus

Operation status envelope.

See AzotteStatus

status.messageCodestring

SUCCESS on hit.

Sample Response

{
  "result": {
    "customerUrn": "cu.00.482",
    "externalIdentifier": "crm-9981273",
    "email": "jane.doe@example.com",
    "status": "Active"
  },
  "status": { "messageCode": "SUCCESS" }
}

Bad Request (HTTP 400)

messageCode	Trigger
BAD_REQUEST	request.Customer is null.
INVALID_REQUEST	FluentValidation rule failed on payload.

Conflict (HTTP 409)

Duplicate identity collision.

messageCode	Trigger
USER_WITH_SAME_PHONE_NUMBER_EXISTS	Phone number already attached to another customer.
USER_WITH_SAME_EMAIL_EXISTS	Email already attached to another customer.
CUSTOMER_ALREADY_STORED	externalIdentifier already projected (call /info or /update instead).

Server Error (HTTP 500)

messageCode	Trigger
SQL_DATABASE_FAILURE	Insert returned null (DB layer rejected the row).
INTERNAL_SERVER_ERROR	Unhandled exception caught by the controller.

Behaviour

• ExternalId uniqueness is enforced per tenant. Colliding ExternalId returns CUSTOMER_ALREADY_STORED (409).
• Email and phone uniqueness enforced per tenant — return USER_WITH_SAME_EMAIL_EXISTS / USER_WITH_SAME_PHONE_NUMBER_EXISTS (409).
• Validation of mandatory tenant-side fields runs via TenantCustomerInfoStorageValidator → INVALID_REQUEST (400).
• Privacy / consent flags are stored verbatim; you remain responsible for the legal basis.

Sample Codes

cURL

curl --location 'https://acme.sandbox.azotte.com/api/v1/c2a/customer/store' \
  --header 'Content-Type: application/json' \
  --header 'x-tn: e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f' \
  --header 'x-api-key: sk_dev_acme_sample_123456789' \
  --data '{
    "customer": {
      "externalIdentifier": "crm-9981273",
      "email": "jane.doe@example.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "legalType": "Individual"
    },
    "claimedRegion": { "countryCode": "DE", "languageCode": "de" }
  }'

JavaScript

const payload = {
  customer: {
    externalIdentifier: 'crm-9981273',
    email: 'jane.doe@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    legalType: 'Individual'
  },
  claimedRegion: { countryCode: 'DE', languageCode: 'de' }
};

const res = await fetch('https://acme.sandbox.azotte.com/api/v1/c2a/customer/store', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tn': 'e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
    'x-api-key': 'sk_dev_acme_sample_123456789'
  },
  body: JSON.stringify(payload)
});
console.log(await res.json());

Node.js

import { request } from 'undici';

const payload = {
  customer: {
    externalIdentifier: 'crm-9981273',
    email: 'jane.doe@example.com',
    firstName: 'Jane',
    lastName: 'Doe',
    legalType: 'Individual'
  },
  claimedRegion: { countryCode: 'DE', languageCode: 'de' }
};

const { body } = await request('https://acme.sandbox.azotte.com/api/v1/c2a/customer/store', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-tn': 'e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
    'x-api-key': 'sk_dev_acme_sample_123456789'
  },
  body: JSON.stringify(payload)
});
console.log(await body.json());

Python

import requests

payload = {
    "customer": {
        "externalIdentifier": "crm-9981273",
        "email": "jane.doe@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "legalType": "Individual",
    },
    "claimedRegion": {"countryCode": "DE", "languageCode": "de"},
}

res = requests.post(
    "https://acme.sandbox.azotte.com/api/v1/c2a/customer/store",
    headers={
        "Content-Type": "application/json",
        "x-tn": "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f",
        "x-api-key": "sk_dev_acme_sample_123456789",
    },
    json=payload,
)
print(res.json())

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String json = """
{
  "customer": {
    "externalIdentifier": "crm-9981273",
    "email": "jane.doe@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "legalType": "Individual"
  },
  "claimedRegion": { "countryCode": "DE", "languageCode": "de" }
}
""";

HttpClient client = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create("https://acme.sandbox.azotte.com/api/v1/c2a/customer/store"))
    .header("Content-Type", "application/json")
    .header("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f")
    .header("x-api-key", "sk_dev_acme_sample_123456789")
    .POST(HttpRequest.BodyPublishers.ofString(json))
    .build();
HttpResponse<String> res = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(res.body());

C#

using System.Net.Http.Json;

var payload = new {
    customer = new {
        externalIdentifier = "crm-9981273",
        email = "jane.doe@example.com",
        firstName = "Jane",
        lastName  = "Doe",
        legalType = "Individual"
    },
    claimedRegion = new { countryCode = "DE", languageCode = "de" }
};

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f");
http.DefaultRequestHeaders.Add("x-api-key", "sk_dev_acme_sample_123456789");

var res = await http.PostAsJsonAsync(
    "https://acme.sandbox.azotte.com/api/v1/c2a/customer/store",
    payload);
Console.WriteLine(await res.Content.ReadAsStringAsync());

PHP

<?php
$payload = [
    'customer' => [
        'externalIdentifier' => 'crm-9981273',
        'email'              => 'jane.doe@example.com',
        'firstName'          => 'Jane',
        'lastName'           => 'Doe',
        'legalType'          => 'Individual',
    ],
    'claimedRegion' => ['countryCode' => 'DE', 'languageCode' => 'de'],
];

$ch = curl_init('https://acme.sandbox.azotte.com/api/v1/c2a/customer/store');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'x-tn: e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f',
        'x-api-key: sk_dev_acme_sample_123456789',
    ],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
echo curl_exec($ch);
curl_close($ch);

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    payload := map[string]any{
        "customer": map[string]any{
            "externalIdentifier": "crm-9981273",
            "email":              "jane.doe@example.com",
            "firstName":          "Jane",
            "lastName":           "Doe",
            "legalType":          "Individual",
        },
        "claimedRegion": map[string]string{"countryCode": "DE", "languageCode": "de"},
    }
    body, _ := json.Marshal(payload)

    req, _ := http.NewRequest("POST",
        "https://acme.sandbox.azotte.com/api/v1/c2a/customer/store",
        bytes.NewReader(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-tn", "e2a1c7b2-4f3a-4b8e-9c2d-1a2b3c4d5e6f")
    req.Header.Set("x-api-key", "sk_dev_acme_sample_123456789")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()
    out, _ := io.ReadAll(res.Body)
    fmt.Println(string(out))
}