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 automatically send an email 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 us 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'
        }
      }

Response

{
	data: null
	success: true
}

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

should_override - whether existing clients with an existing email address should be overridden or not

upload_type - the type or structure of the Clients' payload. Are you importing clients with multiple nested matters or just single client entities?

If you are not sure about this, we recommend using 'single' which is the default for most use cases.

📘

Import session identifier

You'll notice that at no point during the process inTandem creates a session id. Therefore, we recommend using the business_uid value as the import session identifier, assuming that multiple import requests from the same business are not to be expected.

The business_uid value should be avaialble for the app via the redirect_uri as a query param.

Exporting the clients into inTandem

Following a successful response for the above POST request, inTandem will instantly send a GET request to your application's API URI requesting batches of Clients 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}

• business_uid - as suggested above, the business_uid value should let you know the "session id" on behalf of inTandem is now requesting clients.
• staff_uid - the staff on behalf of the import is done. This staff_uid is fetched based on the authorization token used in the initial POST request.
• 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 is lower than the per_page value, we'll assume that that was the last page, and replay

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

the first_name is 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 (see the above screenshot) to the staff email address summarizing the number of imported clients and failed attempts, if any occurred.

Notes and limitations

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