Customers Assignments

Manage customer assignments to segments

Retrieving all customer assignments for a customer segment

get

Retrieves all customer assignments for a given customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve customer assignments for a customer segment

• customersegment.segment_read_own - allows customers to retrieve their own assignments to a active customer segment

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Query parameters

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Responses

200

Customer assignments for a customer segment were successfully retrieved.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

get

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/{segmentId}/customers HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "customer": {
      "id": "98029737",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]"
    },
    "legalEntity": {
      "id": "660af2af69babe3cf6e40771",
      "name": "SomeCompany"
    },
    "assignmentType": "MANUAL",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "customer": {
      "customerId": "18249883",
      "firstName": "Jack",
      "lastName": "Smith",
      "email": "[e-mail]"
    },
    "legalEntity": {
      "id": "448gh29h1d0b5453g6346df6",
      "department": "AnotherCompany"
    },
    "assignmentType": "MANUAL",
    "metadata": {
      "createdAt": "2024-10-16T12:00:00.000Z",
      "modifiedAt": "2024-10-16T12:00:00.000Z",
      "version": 1
    }
  }
]

Searching with parameters for customer assignments

post

Returns all customer assignments that match provided criteria.

Required scopes

• customersegment.segment_read - allows you to retrieve customer assignments for a customer segment

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Query parameters

pageSizestringOptional

The number of documents to be retrieved per page.

pageNumberstringOptional

The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.

sortstringOptional

List of properties used to sort the results, separated by colons.

fieldsstringOptional

Fields to be returned in the response.

Header parameters

X-Total-CountbooleanOptional

Flag indicating whether the total number of retrieved results should be returned.

Body

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

Responses

200

Customer assignments for a customer segment were successfully retrieved.

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

post

HTTPcURLJavaScriptPython

POST /customer-segment/{tenant}/segments/{segmentId}/customers/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "q": "assignmentType:MANUAL"
}

[
  {
    "customer": {
      "id": "98029737",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[e-mail]"
    },
    "legalEntity": {
      "id": "660af2af69babe3cf6e40771",
      "name": "SomeCompany"
    },
    "assignmentType": "MANUAL",
    "metadata": {
      "createdAt": "2024-10-12T12:00:00.000Z",
      "modifiedAt": "2024-10-12T12:00:00.000Z",
      "version": 1
    }
  },
  {
    "customer": {
      "customerId": "18249883",
      "firstName": "Jack",
      "lastName": "Smith",
      "email": "[e-mail]"
    },
    "legalEntity": {
      "id": "448gh29h1d0b5453g6346df6",
      "department": "AnotherCompany"
    },
    "assignmentType": "MANUAL",
    "metadata": {
      "createdAt": "2024-10-16T12:00:00.000Z",
      "modifiedAt": "2024-10-16T12:00:00.000Z",
      "version": 1
    }
  }
]

[B2C] Retrieving a customer assignment for a customer segment

get

Retrieves a customer with specified customerId assigned to a customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve a customer assignment for a active customer segment

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

Query parameters

fieldsstringOptional

Fields to be returned in the response.

Responses

200

Customer assignment for a customer segment was successfully retrieved.

application/json

Responseall of

and

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

404

Resource not found

application/json

get

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "customer": {
    "id": "98029737",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]"
  },
  "assignmentType": "MANUAL",
  "metadata": {
    "createdAt": "2024-10-12T12:00:00.000Z",
    "modifiedAt": "2024-10-12T12:00:00.000Z",
    "version": 1
  }
}

[B2C] Updating a customer assignment for a customer segment

put

Performs UPSERT operation. Updates a customer assigned to a customer segment. A new customer assignment is created if it's not present in the system.

Required scopes

• customersegment.segment_manage - required to add and modify customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

Body

metadataall ofOptional

Responses

201

A new customer assignment was successfully created.

204

Customer assignment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

409

Conflict

application/json

put

HTTPcURLJavaScriptPython

PUT /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 202

{
  "mixins": {
    "segmentAttributes": {
      "membershipStatus": "PREMIUM"
    }
  },
  "metadata": {
    "mixins": {
      "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/segmentAttributes_v1.json"
    }
  }
}

No content

[B2C] Removing a customer from customer segment

delete

Removes customer assignment.

Required scopes

• customersegment.segment_manage - required to delete customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

Responses

204

Customer assignment was successfully removed.

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

delete

HTTPcURLJavaScriptPython

DELETE /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

[B2B] Retrieving a customer assignment for a customer segment

get

Retrieves a customer with specified customerId and companyId assigned to a customer segment.

Required scopes

• customersegment.segment_read - allows you to retrieve a customer assignment for a customer segment

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

legalEntityIdstringRequired

Unique identifier of the legal entity which customer is assigned to.

Query parameters

fieldsstringOptional

Fields to be returned in the response.

Responses

200

Customer assignment for a customer segment was successfully retrieved.

application/json

Responseall of

and

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

404

Resource not found

application/json

get

HTTPcURLJavaScriptPython

GET /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "customer": {
    "id": "98029737",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[e-mail]"
  },
  "legalEntity": {
    "id": "660af2af69babe3cf6e40771",
    "name": "SomeCompany"
  },
  "assignmentType": "MANUAL",
  "metadata": {
    "createdAt": "2024-10-12T12:00:00.000Z",
    "modifiedAt": "2024-10-12T12:00:00.000Z",
    "version": 1
  }
}

[B2B] Updating a customer assignment for a customer segment

put

Performs UPSERT operation. Updates a customer assigned to a customer segment. A new customer assignment is created if it's not present in the system.

Required scopes

• customersegment.segment_manage - required to add and modify customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

legalEntityIdstringRequired

Unique identifier of the legal entity which customer is assigned to.

Body

metadataall ofOptional

Responses

201

A new customer assignment was successfully created.

204

Customer assignment was successfully updated.

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

409

Conflict

application/json

put

HTTPcURLJavaScriptPython

PUT /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 202

{
  "mixins": {
    "segmentAttributes": {
      "membershipStatus": "PREMIUM"
    }
  },
  "metadata": {
    "mixins": {
      "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/segmentAttributes_v1.json"
    }
  }
}

No content

[B2B] Removing a customer from customer segment

delete

Removes customer assignment.

Required scopes

• customersegment.segment_manage - required to delete customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

customerIdstringRequired

Unique identifier of the customer which is added to a customer segment.

legalEntityIdstringRequired

Unique identifier of the legal entity which customer is assigned to.

Responses

204

Customer assignment was successfully removed.

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

delete

HTTPcURLJavaScriptPython

DELETE /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Updating customer assignments for a customer segment in bulk

put

Performs UPSERT operation. Updates multiple customer assignments to a customer segment.

Required scopes

• customersegment.segment_manage - required to add and modify customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Body

itemsall ofOptional

Responses

207

Multi-status response.

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

put

HTTPcURLJavaScriptPython

PUT /customer-segment/{tenant}/segments/{segmentId}/customers/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 365

[
  {
    "customerId": "98029737",
    "legalEntityId": "660af2af69babe3cf6e40771",
    "mixins": {
      "segmentAttributes": {
        "membershipStatus": "PREMIUM"
      }
    },
    "metadata": {
      "mixins": {
        "segmentAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1600077014/schemata/segmentAttributes_v1.json"
      }
    }
  },
  {
    "customerId": "18249883",
    "legalEntityId": "628cd20c6e8b2432b6346ca6",
    "metadata": {
      "version": 1
    }
  }
]

[
  {
    "index": 1,
    "code": 204,
    "status": "OK"
  },
  {
    "index": 2,
    "code": 400,
    "status": "Bad Request",
    "message": "Validation problem with request body."
  }
]

Removing customers from customer segment in bulk

delete

Removes multiple customer assignments to a customer segment.

The request body for this endpoint is array of objects with customerId and legalEntityId fields.

Example: [{"customerId": "firstCustomerId", "legalEntityId": "firstLegalEntityId"}, {"customerId": "secondCustomerId", "legalEntityId": "secondLegalEntityId"}, {"customerId": "thirdCustomerId", "legalEntityId": "thirdLegalEntityId"}]

Required scopes

• customersegment.segment_manage - required to delete customer assignments

Authorizations

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant's name.

Note: Always write the tenant name in lowercase.

Pattern: ^[a-z][a-z0-9]+$

segmentIdstringRequired

Unique identifier of the customer segment.

Responses

207

Multi-status response.

application/json

400

Bad request due to validation, incorrect parameters, etc.

application/json

401

Unauthorized

application/json

403

Access forbidden. The caller is not allowed to access this resource.

application/json

delete

HTTPcURLJavaScriptPython

DELETE /customer-segment/{tenant}/segments/{segmentId}/customers/bulk HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "index": 1,
    "code": 204,
    "status": "OK"
  },
  {
    "index": 2,
    "code": 204,
    "status": "OK"
  }
]