Skip to main content

Contact sync

info

Please contact ITX if you haven't received your third party system id(s) yet.

Terminology​

Contact​

A contact in ITX is an entity representing an individual or organization that interacts with the system. Contacts are categorized into different types, including prospect, customer, debtor, and supplier. Additionally, contacts can be classified as either private or corporate.

Attributes of a contact may include:

  • Type: Indicates whether the contact is a prospect, customer, debtor, or supplier.
  • Private or Corporate: Specifies whether the contact represents an individual or an organization.
  • Contact Information: Includes details such as name, address, email, phone number, and any other relevant contact information.
  • Additional Details: Depending on the type of contact, additional information such as account status, purchasing history, or outstanding balances may be included.

The following image shows a corporate contact with both customer¹ and supplier² extension. Debtor³ is not created

Contact types

Contact Person​

A contact person is an individual associated with a specific contact within the ITX system. Contact persons are typically linked to contacts that represent organizations, rather than individuals.

Attributes of a contact person may include:

  • Role: Describes the position or responsibility of the contact person within the organization.
  • Title: Specifies the professional title or designation of the contact person.
  • Name: The full name of the contact person.
  • Contact Information: Includes details such as email address, phone number, and any other relevant contact information.

In summary, a contact represents an entity within the ITX system, which can be either an individual or an organization, categorized by type and further distinguished as private or corporate. A contact person, on the other hand, refers specifically to individuals associated with contacts, providing additional details such as role, title, and contact information.

A contact link is a structure which links a given contact person to a contact. The link itself describes the type of relation, and may include information such as title and role.

Third party system​

The Third Party System ID is a unique identifier assigned to each ITX customer. You may have multiple Third Party System IDs associated with your system, each serving a distinct purpose. These IDs typically include an internal customer ID, which is often generated automatically (e.g., auto-incremented or UUID), and a public-facing customer ID, which is frequently a sequential customer number known to your contact.

The Third Party System ID serves as a crucial reference point between our system and the your system. It acts as a key identifier that enables seamless communication and data exchange between the two systems. Without this ID, or by incorrect usage, you may risk getting multiple duplicates of your contacts and/or contact persons.

When retrieving, creating, or updating contacts and contact persons, the Third Party System ID must be provided. This ID ensures accurate identification and synchronization of customer data across both systems.

API description​

OpenAPI Specification:

For detailed technical information about each endpoint, including request and response formats, authentication requirements, and example payloads, please refer to our OpenAPI specification.

Contact​

Endpoints:

Our endpoint naming convention follows a specific format to distinguish between different types of contacts. Contact-related endpoints follow the following format:

/v1/<private/corporate><contact_type>

  • <private/corporate>: Specifies whether the contact is private or corporate.
  • <contact_type>: Indicates the type of contact (e.g., customer, supplier).

Examples:

  • /v1/privatecustomer: This endpoint is used to interact with private customers.
  • /v1/corporatecustomer: This endpoint is used to interact with corporate customers.
  • /v1/corporatesupplier: This endpoint is used to interact with corporate suppliers.

Contact person​

Concat person

  • GET ​/v1​/contactperson
  • POST ​/v1​/contactperson

Concat link

  • GET ​/v1​/contactlink
  • POST ​/v1​/contactlink
  • DELETE ​/v1​/contactlink

General Flow​

  1. Understand Contact Types: Familiarize yourself with the different types of contacts within the ITX system, including prospects, customers, debtors, and suppliers. Determine which types of contacts your integration will interact with.

  2. Determine Contact Classification: Identify whether the contacts your integration will handle are private individuals or corporate entities. This distinction will impact the endpoints and data structure used during integration.

  3. Retrieve Third Party System IDs: Ensure you have access to Third Party System IDs associated with your system. These unique identifiers are crucial for accurate identification and synchronization of customer data across systems.

  4. Choose Endpoint Based on Contact Type: Select the appropriate endpoint based on the type and classification of the contact you want to interact with. Use the following endpoint formats:

    • /v1/<private/corporate><contact_type>

  5. Contacts:

    • GET Request:
      • Use GET requests to retrieve existing contacts based on your third party system ID. Use query parameters extSystemEstpId and extSystemId.
    • POST Request:
      • If the Third Party System ID does not exist, the POST request will create a new contact.
      • If the Third Party System ID already exists, the POST request will update existing contact details.

  6. Contact Persons:

    • GET Request:
      • Use GET requests to retrieve existing contact persons based on your third party system ID. Use query parameters extSystemEstpId and extSystemId.
    • POST Request:
      • Use the POST request to create contact persons associated with specific contacts.

  7. Contact links:

    • GET Request:
      • Use GET requests to search for links eighter by idFrom or idTo. The links itself will be contained in contact GET and contact person GET in addition to the respective POST response data.
    • POST Request:
      • Use the POST request to establish links between contact persons and contacts.
      • Specify the type of relation and include additional information such as title and role.
    • DELETE Request:
      • Use DELETE requests to delete a contact person link based on the contact person link ID.

  8. Webhooks:

    • ITX can configure webhooks on creation, update and delete events if needed. You will need to provide us with one or multiple endpoints which the payloads will be delivered too.