Emporix Customers Assignments API

openapi: 3.2.0
info:
  title: Emporix Customers Assignments API
  version: ''
  contact:
    email: documentation@emporix.com
  description: 'Operations tagged Customers Assignments across 2 of this provider''s published API definitions: emporix-customer-segments-openapi.yml, emporix-customer-segments-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.emporix.io
security:
- OAuth2: []
tags:
- name: Customers Assignments
  description: Manage customer assignments to segments
paths:
  /customer-segment/{tenant}/segments/{segmentId}/customers:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/segmentId'
    get:
      summary: Retrieving all customer assignments for a customer segment
      tags:
      - Customers Assignments
      description: Retrieves all customer assignments for a given customer segment.
      security:
      - CustomerAccessToken: []
      - OAuth2:
        - customersegment.segment_read
        - customersegment.segment_read_own
      responses:
        '200':
          description: Customer assignments for a customer segment were successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerAssignmentResponse'
              examples:
                Customer Assignments:
                  $ref: '#/components/examples/CustomerAssignmentsResponse'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
      operationId: GET-customer-segment-retrieve-customers
      parameters:
      - $ref: '#/components/parameters/qParam'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/xTotalCount'
    servers:
    - url: https://api.emporix.io
  /customer-segment/{tenant}/segments/{segmentId}/customers/search:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/segmentId'
    post:
      summary: Searching with parameters for customer assignments
      tags:
      - Customers Assignments
      description: Returns all customer assignments that match provided criteria.
      security:
      - OAuth2:
        - customersegment.segment_read
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SegmentsSearch'
            examples:
              Search Segments:
                value:
                  q: assignmentType:MANUAL
      responses:
        '200':
          description: Customer assignments for a customer segment were successfully retrieved.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomerAssignmentResponse'
              examples:
                Customer Assignments:
                  $ref: '#/components/examples/CustomerAssignmentsResponse'
        '400':
          $ref: '#/components/responses/Common_response_BadRequest_400'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
      operationId: POST-customer-segment-search-customers
      parameters:
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/pageNumber'
      - $ref: '#/components/parameters/sort'
      - $ref: '#/components/parameters/fields'
      - $ref: '#/components/parameters/xTotalCount'
    servers:
    - url: https://api.emporix.io
  /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId}:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/segmentId'
    - schema:
        type: string
      name: customerId
      in: path
      description: Unique identifier of the customer which is added to a customer segment.
      required: true
    get:
      summary: '[B2C] Retrieving a customer assignment for a customer segment'
      tags:
      - Customers Assignments
      description: Retrieves a customer with specified customerId assigned to a customer segment.
      security:
      - OAuth2:
        - customersegment.segment_read
      responses:
        '200':
          description: Customer assignment for a customer segment was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAssignmentB2CResponse'
              examples:
                Customer Assignment Response:
                  $ref: '#/components/examples/CustomerAssignmentB2CResponse'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
        '404':
          $ref: '#/components/responses/Common_response_NotFound_404'
      operationId: GET-customer-segment-retrieve-customer-by-customerId
      parameters:
      - $ref: '#/components/parameters/fields'
    put:
      summary: '[B2C] Updating a customer assignment for a customer segment'
      tags:
      - Customers Assignments
      operationId: PUT-customer-segment-update-customer-by-customerId
      description: 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.
      security:
      - OAuth2:
        - customersegment.segment_manage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerAssignmentUpsert'
            examples:
              Customer Assignment Update:
                $ref: '#/components/examples/CustomerAssignmentUpsert'
      responses:
        '201':
          description: A new customer assignment was successfully created.
        '204':
          description: Customer assignment was successfully updated.
        '400':
          $ref: '#/components/responses/Common_response_BadRequest_400'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
        '409':
          $ref: '#/components/responses/Common_response_Conflict_409'
    delete:
      summary: '[B2C] Removing a customer from customer segment'
      tags:
      - Customers Assignments
      operationId: DELETE-customer-segment-remove-customer-by-customerId
      description: Removes customer assignment.
      security:
      - OAuth2:
        - customersegment.segment_manage
      responses:
        '204':
          description: Customer assignment was successfully removed.
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
    servers:
    - url: https://api.emporix.io
  /customer-segment/{tenant}/segments/{segmentId}/customers/{customerId}/{legalEntityId}:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/segmentId'
    - schema:
        type: string
      name: customerId
      in: path
      description: Unique identifier of the customer which is added to a customer segment.
      required: true
    - schema:
        type: string
      name: legalEntityId
      in: path
      description: Unique identifier of the legal entity which customer is assigned to.
      required: true
    get:
      summary: '[B2B] Retrieving a customer assignment for a customer segment'
      tags:
      - Customers Assignments
      description: Retrieves a customer with specified customerId and companyId assigned to a customer segment.
      security:
      - OAuth2:
        - customersegment.segment_read
      responses:
        '200':
          description: Customer assignment for a customer segment was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerAssignmentResponse'
              examples:
                Customer Assignment Response:
                  $ref: '#/components/examples/CustomerAssignmentResponse'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
        '404':
          $ref: '#/components/responses/Common_response_NotFound_404'
      operationId: GET-customer-segment-retrieve-customer
      parameters:
      - $ref: '#/components/parameters/fields'
    put:
      summary: '[B2B] Updating a customer assignment for a customer segment'
      tags:
      - Customers Assignments
      operationId: PUT-customer-segment-update-customer
      description: 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.
      security:
      - OAuth2:
        - customersegment.segment_manage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomerAssignmentUpsert'
            examples:
              Customer Assignment Update:
                $ref: '#/components/examples/CustomerAssignmentUpsert'
      responses:
        '201':
          description: A new customer assignment was successfully created.
        '204':
          description: Customer assignment was successfully updated.
        '400':
          $ref: '#/components/responses/Common_response_BadRequest_400'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
        '409':
          $ref: '#/components/responses/Common_response_Conflict_409'
    delete:
      summary: '[B2B] Removing a customer from customer segment'
      tags:
      - Customers Assignments
      operationId: DELETE-customer-segment-remove-customer
      description: Removes customer assignment.
      security:
      - OAuth2:
        - customersegment.segment_manage
      responses:
        '204':
          description: Customer assignment was successfully removed.
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
    servers:
    - url: https://api.emporix.io
  /customer-segment/{tenant}/segments/{segmentId}/customers/bulk:
    parameters:
    - $ref: '#/components/parameters/tenant'
    - $ref: '#/components/parameters/segmentId'
    put:
      summary: Updating customer assignments for a customer segment in bulk
      tags:
      - Customers Assignments
      operationId: PUT-customer-segment-update-customers-bulk
      description: Performs `UPSERT` operation. Updates multiple customer assignments to a customer segment. The maximum batch size is 200.
      security:
      - OAuth2:
        - customersegment.segment_manage
      requestBody:
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/CustomerAssignmentUpsertBulk'
            examples:
              Customer Assignment Update:
                $ref: '#/components/examples/CustomerAssignmentsUpsert'
      responses:
        '207':
          description: Multi-status response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkAssignmentResponse'
              examples:
                Customer Assignments Update:
                  $ref: '#/components/examples/BulkAssignmentUpdateResponse'
        '400':
          $ref: '#/components/responses/Common_response_BadRequest_400'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
    delete:
      summary: Removing customers from customer segment in bulk
      tags:
      - Customers Assignments
      operationId: DELETE-customer-segment-remove-customers-bulk
      description: 'Removes multiple customer assignments to a customer segment. The maximum batch size is 200.


        ### 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"}]`'
      security:
      - OAuth2:
        - customersegment.segment_manage
      responses:
        '207':
          description: Multi-status response.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BulkAssignmentResponse'
              examples:
                Customer Assignments Deletion:
                  $ref: '#/components/examples/BulkAssignmentDeletionResponse'
        '400':
          $ref: '#/components/responses/Common_response_BadRequest_400'
        '401':
          $ref: '#/components/responses/Common_response_Unauthorized_401'
        '403':
          $ref: '#/components/responses/Common_response_Forbidden_403'
    servers:
    - url: https://api.emporix.io
components:
  parameters:
    qParam:
      in: query
      name: q
      description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
      schema:
        type: string
    sort:
      schema:
        type: string
      in: query
      name: sort
      description: List of properties used to sort the results, separated by colons.
    tenant:
      name: tenant
      in: path
      required: true
      description: 'Your Emporix tenant name.


        **Note**: Always write the tenant name in lowercase.

        '
      schema:
        pattern: ^[a-z][a-z0-9]+$
        minLength: 3
        maxLength: 16
        type: string
    segmentId:
      name: segmentId
      in: path
      required: true
      description: Unique identifier of the customer segment.
      schema:
        type: string
    xTotalCount:
      schema:
        type: boolean
      in: header
      name: X-Total-Count
      description: Flag indicating whether the total number of retrieved results should be returned.
    pageNumber:
      schema:
        type: string
      in: query
      name: pageNumber
      description: The page number to be retrieved. The size of the pages should be specified by the pageSize parameter.
    pageSize:
      schema:
        type: string
      in: query
      name: pageSize
      description: The number of documents to be retrieved per page.
    fields:
      schema:
        type: string
      in: query
      name: fields
      description: Fields to be returned in the response.
  schemas:
    BulkAssignmentResponse:
      type: object
      properties:
        index:
          type: integer
          description: 'Index of the processed item, matching the item position in request body.

            '
        code:
          type: integer
          description: HTTP Status Code.
        status:
          type: string
          description: HTTP Status description.
        message:
          type: string
          description: Error message.
    LegalEntity:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of an existing legal entity.
        name:
          type: string
          description: Name of a legal entity.
    MetadataUpdate:
      allOf:
      - type: object
        properties:
          version:
            type: integer
            description: The document version number.
      - $ref: '#/components/schemas/MetadataCreate'
    CustomerAssignmentUpsertBulk:
      allOf:
      - $ref: '#/components/schemas/CustomerAssignmentUpsert'
      - type: object
        properties:
          customerId:
            type: string
            description: Unique identifier of an existing customer.
          legalEntityId:
            type: string
            description: Unique identifier of an existing legal entity. It should be omitted for B2C.
    MetadataCreate:
      type: object
      properties:
        mixins:
          type: object
          description: A key-value map, where key is a mixin name and value is a link to the mixin schema.
          additionalProperties: true
    CustomerAssignmentResponse:
      allOf:
      - type: object
        properties:
          legalEntity:
            $ref: '#/components/schemas/LegalEntity'
      - $ref: '#/components/schemas/CustomerAssignmentB2CResponse'
    Customer:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of an existing customer.
        firstName:
          type: string
          description: Customer's first name.
        lastName:
          type: string
          description: Customer's last name.
        email:
          type: string
          description: Customer's e-mail address.
    Error:
      type: object
      properties:
        code:
          type: integer
          description: HTTP Status Code.
        status:
          type: string
          description: HTTP Status.
        message:
          type: string
          description: Error message.
        resourceId:
          type: string
          description: An ID of the resource which caused the error.
        details:
          type: object
          description: Error details
          properties:
            field:
              type: string
            type:
              type: string
            message:
              type: string
            moreInfo:
              type: string
    SegmentsSearch:
      type: object
      properties:
        q:
          type: string
          description: "A standard query parameter is used to search for specific values. \n\nSee: [Standard Practices - Query parameter](https://developer.emporix.io/api-documentation/standard-practices/q-param)\n"
    CustomerAssignmentB2CResponse:
      allOf:
      - type: object
        properties:
          customer:
            $ref: '#/components/schemas/Customer'
      - type: object
        properties:
          assignmentType:
            type: string
            enum:
            - MANUAL
            - AUTOMATIC
      - $ref: '#/components/schemas/CustomerAssignmentUpsert'
      - type: object
        properties:
          metadata:
            $ref: '#/components/schemas/MetadataResponse'
    CustomerAssignmentUpsert:
      type: object
      description: ''
      properties:
        mixins:
          type: object
          description: A key-value map of additional attributes.
          additionalProperties: true
        metadata:
          $ref: '#/components/schemas/MetadataUpdate'
    MetadataResponse:
      allOf:
      - type: object
        properties:
          createdAt:
            description: The creation date.
            type: string
            format: date-time
          modifiedAt:
            description: The modification date.
            type: string
            format: date-time
      - $ref: '#/components/schemas/MetadataUpdate'
  examples:
    Response_BadRequest_400:
      value:
        code: 400
        status: Bad Request
        message: Validation problem with request body.
    Response_Forbidden_403:
      value:
        code: 403
        status: Forbidden
        message: The access to the requested resource has been forbidden by the server.
    Response_Conflict_409_changed:
      value:
        code: 409
        status: Conflict
        message: The resource you are attempting to access has changed.
    BulkAssignmentUpdateResponse:
      value:
      - index: 1
        code: 204
        status: OK
      - index: 2
        code: 400
        status: Bad Request
        message: Validation problem with request body.
    CustomerAssignmentsUpsert:
      value:
      - customerId: '98029737'
        legalEntityId: 660af2af69babe3cf6e40771
        mixins:
          segmentAttributes:
            membershipStatus: PREMIUM
        metadata:
          mixins:
            segmentAttributes: https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/69537caeb3fd5d378296ae42_segmentAttributes.json
      - customerId: '18249883'
        legalEntityId: 628cd20c6e8b2432b6346ca6
        metadata:
          version: 1
    CustomerAssignmentB2CResponse:
      value:
        customer:
          id: '98029737'
          firstName: John
          lastName: Doe
          email: john.doe@email.com
        assignmentType: MANUAL
        metadata:
          createdAt: 2024-10-12 12:00:00+00:00
          modifiedAt: 2024-10-12 12:00:00+00:00
          version: 1
    CustomerAssignmentResponse:
      value:
        customer:
          id: '98029737'
          firstName: John
          lastName: Doe
          email: john.doe@email.com
        legalEntity:
          id: 660af2af69babe3cf6e40771
          name: SomeCompany
        assignmentType: MANUAL
        metadata:
          createdAt: 2024-10-12 12:00:00+00:00
          modifiedAt: 2024-10-12 12:00:00+00:00
          version: 1
    Response_Conflict_409_exists:
      value:
        code: 409
        status: Conflict
        message: The resource already exists.
    CustomerAssignmentsResponse:
      value:
      - customer:
          id: '98029737'
          firstName: John
          lastName: Doe
          email: john.doe@email.com
        legalEntity:
          id: 660af2af69babe3cf6e40771
          name: SomeCompany
        assignmentType: MANUAL
        metadata:
          createdAt: 2024-10-12 12:00:00+00:00
          modifiedAt: 2024-10-12 12:00:00+00:00
          version: 1
      - customer:
          customerId: '18249883'
          firstName: Jack
          lastName: Smith
          email: jack.smith@email.com
        legalEntity:
          id: 448gh29h1d0b5453g6346df6
          department: AnotherCompany
        assignmentType: MANUAL
        metadata:
          createdAt: 2024-10-16 12:00:00+00:00
          modifiedAt: 2024-10-16 12:00:00+00:00
          version: 1
    BulkAssignmentDeletionResponse:
      value:
      - index: 1
        code: 204
        status: OK
      - index: 2
        code: 204
        status: OK
    CustomerAssignmentUpsert:
      value:
        mixins:
          segmentAttributes:
            membershipStatus: PREMIUM
        metadata:
          mixins:
            segmentAttributes: https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/69537caeb3fd5d378296ae42_segmentAttributes.json
    Response_NotFound_404:
      value:
        code: 404
        status: Not Found
        message: The resource with id 628cd20c6e8b2432b6346ca6 has not been found.
  responses:
    Common_response_Unauthorized_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              fault:
                type: object
                properties:
                  faultstring:
                    type: string
                  detail:
                    type: object
                    properties:
                      errorcode:
                        type: string
          examples:
            Invalid access token:
              value:
                fault:
                  faultstring: Invalid access token
                  detail:
                    errorcode: oauth.v2.InvalidAccessToken
    Common_response_Conflict_409:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Conflict - resource exists:
              $ref: '#/components/examples/Response_Conflict_409_exists'
            Conflict - resource has changed:
              $ref: '#/components/examples/Response_Conflict_409_changed'
    Common_response_Forbidden_403:
      description: Access forbidden. The caller is not allowed to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Forbidden:
              $ref: '#/components/examples/Response_Forbidden_403'
    Common_response_BadRequest_400:
      description: Bad request due to validation, incorrect parameters, etc.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Validation Error:
              $ref: '#/components/examples/Response_BadRequest_400'
    Common_response_NotFound_404:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            Not Found:
              $ref: '#/components/examples/Response_NotFound_404'
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.emporix.io/oauth/token
          scopes:
            customersegment.segment_manage: Needed to create or update customer segments.
            customersegment.segment_read: Needed to read customer segments.
            customersegment.segment_read_own: Needed to read own customer segments.
    CustomerAccessToken:
      type: http
      scheme: bearer
      description: To generate a customer access token, go to the [Logging in a customer](https://developer.emporix.io/api-documentation/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-login) endpoint.
x-refined-from:
- emporix-customer-segments-openapi.yml
- emporix-customer-segments-openapi.yml