Client Import

An application type for bulk-importing clients

Overview

The purpose of a Client Import application is to simplify the process of bulk-importing clients and avoid creating them one by one via the Create Client API.

The import capability can be useful for applications that integrate or sync a large number of clients from 3rd party systems into inTandem.

How does it work?

The Client Import app creates a session between your app and inTandem where inTandem will constantly ask for Client data from your app, each time with a parameter called "page" that gets incremented upon each request. When the app is done returning all clients it wants to import, inTandem will send one last request with a Page value of -1, indicating that the import was completed.

When the import completes, inTandem will send an email (optional) to the staff member initiating the import, indicating that a client import was completed.

Developers guide

Initiating an import

API reference: https://developers.intandem.tech/reference/post_v1-apps-app-code-name-import

The first step of a client import is declaring the import to inTandem. This is done by the following POST request, where you let inTandem know the client fields to be expected as part of the import, as well as some additional import configurations detailed below.

POST https://api.vcita.biz/business/clients/v1/apps/{YOUR_APP_CODE_NAME}/import

Request payload

{
        fields_mapping: {
          email: string,
          first_name: string,
          last_name: string,
          phone: string,
          address: string
        },
        import_params: {
          should_override: boolean,
          upload_type: 'single' | 'multi',
          send_notifications_when_done: boolean
        }
      }

Response

{
	success: true,
  data: {
    	session_id: string
  }
}

fields_mapping

The fields_mapping object should specify the client fields that will be part of the Clients JSON you're planning to import. The keys (email, first_name, etc) should correspond to inTandem's field names, and the value is the field's display name as configured by the business.

You can get the list of business' client-card fields using this API: https://developers.intandem.tech/reference/get_fields.

📘

Custom fields

The fields_mapping also supports custom fields (like an external identifier from the 3rd party system, etc), but those must be configured on the business first. If you try mapping to non-existing client fields it'll not break the import, but these fields will be ignored during the import.

import_params

Exporting the clients into inTandem

Following a successful response to the above POST request, inTandem will instantly send a GET request to your application's API URI requesting batches of Client data in return.

Export request

The request will be sent to a /app/clients/export path under the application's api_uri, along with several query params. Here's an example of such a GET request URL:

GET {APPLICATION_API_URI}/app/clients/export?
  business_uid={BUSINESS_UID}&
  staff_uid={STAFF_UID}&
  page={PAGE}&
  per_page={PER_PAGE}&
  session_id={SESSION_ID}

• page - the current page of clients to be exported. The initial page value is 1, and it gets incremented upon each new export request. A page with a value of -1 will be sent as an indication for ending the import session.
• per_page - the number of clients expected on each batch. If the number of clients sent in the response is lower than the per_page value, we'll assume that that was the last page, and close the import session.
• session_id - unique identifier of the import session, corresponding to the session id you received when initiating the import session.

Export response

Response payload should look like so (you can, of course, use any other set of fields):

{
  data: {
    clients: [
              {
                first_name: "Rufus",
                last_name: "Zboncak",
                email: "[email protected]",
                phone: "1-540-672-1284",
                external_id: 4
              },
              {
                first_name: "Darren",
                last_name: "Raynor",
                email: "[email protected]",
                phone: "(300) 045-4811",
                external_id: 5
              }
            ]
        }
}

📘

Mandatory fields

first_name and external_id are a mandatory fields. All other fields are optional.

Import completion

An import completion is determined when the number of clients sent in the GET response are lower than the per_page value. When that happens, inTandem assumes that all clients were exported and will sent one last GET request with a page value of -1, indicating the ending of the import session.

Once all clients are successfully imported into the account, inTandem will send a summary email in case it was requested (see the above screenshot) to the staff email address summarizing the number of imported clients and failed attempts, if any occurred.

Bulk import webhooks and reporting

In case you need to get a report of the import session, or to know if some clients failed to import, you can subscribe to the "bulk_import/done" webhook.

The bulk_import/done event will emit after each bulk, or page, of imported clients.

Event payload example

 {
      "data": {
        "session_id": "0a35841d-d6af-40ca-82b5-0ba1dcbf4970",
        "processed_entity": "clients",
        "import_done": false,
        "page": 2,
        "clients_import_status": {
          "created": {
            "count": 2,
            "external_ids": [
              435647,
              665674
            ]
          },
          "failed": {
            "external_ids": [],
            "count": 0
          },
          "updated": {
            "count": 0,
            "external_ids": []
          },
          "skipped": {
            "count": 0,
            "external_ids": []
          }
        }
      },
      "entity_name": "bulk_import",
      "event_type": "done"
    }

Notes and limitations

• You can import up to 50,000 clients per import session
• Imported clients will automatically be created with the tag "imported_{DATE_TIME}" and a "source" value of the application's name.