API docs by Redocly

Single Customer View (SCV) APIs (1.0.0)

Download OpenAPI specification:

License: Proprietary

Purpose

This document describes the HTTP API for Single Customer View (SCV): customer data and exports.

Authorization

Backend: send x-dxp-tenant and x-api-key on every request.

Frontend: authenticate with the session only — the dxp-sessionid cookie.

Response projection (retAllProps / retProps)

  • retAllProps=1: responses include all customer attributes allowed by the tenant's configured schema (not restricted to retProps), including event-related fields where the schema defines them. $eventLog is included when returning full attributes.
  • Otherwise: omit retAllProps (or do not set it to 1) and use retProps as a comma-separated list to select a subset (including $-prefixed system fields such as $customerid, $segments).

Error responses

  • Authentication failures may return {"message":"Unauthorized"}.
  • Validation and application errors often return title, status, and optionally invalid-params.

SCV API — Customers (backend)

Search customers (list)

Required privilege: CUSTOMERS_READ

Search: exactly one dimension — username, email, tertiary, segment (segment code resolved to id), or search[contains].

Projection: optional retAllProps=1 or retProps (comma-separated; $ prefixes such as $customerid, $segments). See Response projection in the introduction.

Pagination: optional page[size], page[before], page[after] (mutually exclusive before/after).

Sort: optional segmentedDate, createdDate, updatedDate, with leading - for descending.

Authorizations:
(DxpTenantDXPAuth)
query Parameters
username
string
email
string
tertiary
string
segment
string

Segment code (resolved server-side).

search[contains]
string

Case-insensitive substring search.

retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string

Comma-separated attributes, e.g. $customerid,$segments

sort
string
page[size]
integer
page[before]
string
page[after]
string

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {
    }
}

Create customer

Required privilege: CUSTOMER_CREATE

Body may be {} or a partial profile; attributes must validate against the tenant schema. Returns 201 with $customerid on success.

Authorizations:
(DxpTenantDXPAuth)
query Parameters
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string
Request Body schema: application/json
optional
property name*
additional property
any

Responses

Request samples

Content type
application/json
Example
{
  • "$verifiedEmail": "user@example.com",
  • "$username": "postman@squiz.net",
  • "$tertiaryid": "abc123",
  • "firstName": "Bilbo",
  • "lastName": "Baggins",
  • "consented": true
}

Response samples

Content type
application/json
{
  • "$customerid": "9579fe91-b7d0-4f96-be52-e68fa86ec287"
}

Get one customer by id

Required privilege: CUSTOMER_READ

Use retAllProps=1 or retProps like the list endpoint (see Response projection in the introduction).

Authorizations:
(DxpTenantDXPAuth)
path Parameters
customerid
required
string <uuid>
query Parameters
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string

Responses

Response samples

Content type
application/json
{ }

Patch customer (merge)

Required privilege: CUSTOMER_UPDATE

Authorizations:
(DxpTenantDXPAuth)
path Parameters
customerid
required
string <uuid>
query Parameters
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "firstName": "Bilbo",
  • "lastName": "Baggins 3"
}

Response samples

Content type
application/json
{ }

Put customer

Required privilege: CUSTOMER_UPDATE

Default query mode is overwrite, which currently returns 501 Not Implemented. Use ?mode=merge for merge create/update: 201 if created, 200 if updated. customerid must be UUID v4. 409 if another customer already owns the same email.

Authorizations:
(DxpTenantDXPAuth)
path Parameters
customerid
required
string <uuid>
query Parameters
mode
string
Default: "overwrite"
Enum: "merge" "overwrite"
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{ }

Delete customer

Required privilege: CUSTOMER_DELETE

Response body may be JSON null with status 204.

Authorizations:
(DxpTenantDXPAuth)
path Parameters
customerid
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "status": 0,
  • "invalid-params": [
    ]
}

SCV API — Customers (frontend session)

Get current session customer (full profile)

Resolves the customer from the session. Supports retAllProps, retProps (see Response projection in the introduction), and retMetadata=attributes (returns metadata alongside attributes when metadata is requested — see handler implementation).

Authorizations:
DXPSession
query Parameters
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string
retMetadata
string
Value: "attributes"

Responses

Response samples

Content type
application/json
{ }

Get current session customer (alias)

Same behavior as GET /getCustomer for the session-backed customer profile.

Authorizations:
DXPSession
query Parameters
retAllProps
string
Value: "1"

When 1, return all attributes per the tenant schema (see Response projection in the introduction). Omit and use retProps for a subset.

retProps
string
retMetadata
string
Value: "attributes"

Responses

Response samples

Content type
application/json
{ }

Patch current session customer

Empty body returns 400 Missing request body. Invalid JSON returns 400 Invalid JSON. Success returns 200 with an empty JSON object {}.

Authorizations:
DXPSession
Request Body schema: application/json
required
property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "firstName": "John",
  • "lastName": "Smith",
  • "gpa": 2.3
}

Response samples

Content type
application/json
{ }

SCV API — Export

Start customer export for a segment

Required privilege: CUSTOMERS_EXPORT

JSON body must include segment. Returns 202 with exportid.

Authorizations:
(DxpTenantDXPAuth)
Request Body schema: application/json
required
segment
required
string

Responses

Request samples

Content type
application/json
{
  • "segment": "85acd"
}

Response samples

Content type
application/json
{
  • "exportid": "2023-11-01T02:44:15.814Z_85acd"
}

List customer exports

Required privilege: CUSTOMERS_EXPORT

Returns a data array of export records.

Authorizations:
(DxpTenantDXPAuth)

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get export status and signed URL

Required privilege: CUSTOMERS_EXPORT

404 if the export processing marker is missing. signedURL is null until the CSV exists.

Authorizations:
(DxpTenantDXPAuth)
path Parameters
exportid
required
string

Responses

Response samples

Content type
application/json
{
  • "exportid": "2023-11-01T02:44:15.814Z_85acd",
  • "signedURL": null
}