Importing data

Where possible, Movement recommends working with us to set up a full integration, including syncronising your organisation structure. However it is also possible to programatically insert or update target data using the API.

The Targets: Bulk Upsert API method allows you to insert/update the same data that can be uploaded in a CSV, via the interface. All the same columns are supported as with a CSV upload, however the format of the keys is changed to lowercase underscore - e.g. Phone Number becomes phone_number. See all supported columns.

To determine which custom fields exist and can be uploaded, you can use the /custom_fields endpoint.

An example cURL request is below:

curl https://subdomain.yourmovement.org/api/targets/bulk_upsert \
   -XPOST \
   -H 'Authorization: Bearer API_TOKEN'  \
   -H 'Content-Type: application/json' \
   -d '{"records": [
     { "external_id": "TEST1", "first_name": "Test", "last_name": "Target", "phone_number": "07565000000", "custom_field_1": 1.2},
     { "external_id": "TEST2", "first_name": "Test", "last_name": "Target2", "phone_number": "07565000001", "custom_field_1": 3.1 }
     ]}'

Each API call can contain up to 1,000 records, containing core fields, custom fields, and so on. It is also possible to specify a pre-signed URL to a secure CSV, which will then be asynchronously imported. There is no row limit for CSVs, and they conform to the same specifications expected from JSON objects, with columns instead of properties.

Custom field data

There are currently 3 kinds of custom fields within Movement:

1. Text
2. Float
3. Date

Each of these can be retrieved and upserted via the API, in the following way:

1. Text custom fields are pushed in as strings: "Custom Field"
2. Floats are pushed in as floats: 1.1 or 1
3. Dates are passed in YYYY-MM-DD format: 2023-10-01

Updating organisations on upsert

If it is configured, you can update the organisations that a target belongs to by updating the custom fields corresponding to those organisation kinds. You can find the custom fields that are configured for this, using the /organisations/schema endpoint.