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
get
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": "[email protected]"
    },
    "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": "[email protected]"
    },
    "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
post
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": "[email protected]"
    },
    "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": "[email protected]"
    },
    "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
get
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": "[email protected]"
  },
  "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.
put
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.
delete
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
get
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": "[email protected]"
  },
  "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.
put
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.
delete
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.

Bodyall of[]
itemsall ofOptional
Responses
207
Multi-status response.
application/json
put
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
delete
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"
  }
]

Was this helpful?