Bulk Profile Import API

This guide will walk you through our new Bulk Profile Import API. If you have worked with our list upload feature or SFTP import tool, you can now access this same functionality with Klaviyo’s Bulk Profile Import API.

The Bulk Profile Import API performs an upsert, meaning it will update matching profiles if they already exist in your account or create them if no matching profiles are found. You can also optionally add these profiles to a list.

Here are some example use cases supported by the Bulk Profile Import API:

• Import many profiles as part of onboarding.
• Update custom properties to deliver personalized experiences in flow & campaign messaging (e.g., preferences, favorite color, birthday, etc.).
• Update core profile properties (identifiers such as email or phone number, location, etc.) on a regular basis.
• Sync segments from an external system to Klaviyo for targeting in campaigns or flows. Learn more about our robust segmentation system.

🚧

This endpoint should not be used for updating a small number of profiles. In those cases, we recommend using our synchronous profile APIs for more efficient processing.

Common use cases

Submit an import job

The example below is an example request payload to the Spawn Bulk Profile Import Job endpoint. Note that the profile object that can be passed is consistent with the one used by the Create or Update Client Profile endpoint.

{
  "data": {
    "type": "profile-bulk-import-job",
    "attributes": {
      "profiles": {
        "data": [
            {
              "type": "profile",
              "attributes": {
                  "email": "[email protected]", 
                  "properties": {
                      "preferences": ["comedy", "drama"] 
                  }
              }
          },
          {
              "type": "profile",
              "attributes": {
                  "email": "[email protected]",
                  "properties": {
                      "preferences": ["dramedy", "action"] 
                  }
              }
          }
          ...
        ]
      }
    }
  }
}

Sync list(s) to Klaviyo

You may be syncing lists to Klaviyo with our legacy v1/v2 endpoint Add Members to a List. To reference existing profiles (or create new ones in Klaviyo) and add them to a list, call Spawn Bulk Profile Import Job with a request body like the one below:

{
    "data": {
        "type": "profile-bulk-import-job",
        "attributes": {
            "profiles": {
                "data": [
                    {
                        "type": "profile",
                        "attributes": {
                            "email": "[email protected]"
                        }
                    },
                    {
                        "type": "profile",
                        "attributes": {
                            "email": "[email protected]"
                        }
                    }
                ]
            }
        },
        "relationships": {
            "lists": {
                "data": [
                    {
                        "type": "list",
                        "id": "INSERT_LIST_ID"
                    }
                ]
            }
        }
    }
}

As in the Submit an import job example above, you can include additional fields on these profiles, but a minimum of 1 identifier (email, phone_number, etc.) is required.

Retrieve import jobs

Call Get Bulk Profile Import Job to retrieve all bulk profile import jobs. You can use filtering on this endpoint to list all jobs that haven’t been processed yet:

GET /api/profile-bulk-import-jobs/?filter=any(status,["queued","processing"])

Retrieve import status

Retrieve a single bulk profile import job by calling Get Bulk Profile Import Job with a given job ID. You can use filtering to return only the status of a specific bulk import job:

GET /api/profile-bulk-import-jobs/{job_id}/?fields[profile-bulk-import-job]=status

Retrieve import errors

To retrieve any errors that occurred during a job’s processing, call the Get Bulk Profile Import Job Errors endpoint (see Job processing errors):

GET /api/profile-bulk-import-jobs/:id/import-errors/

Retrieve successfully imported profiles

Call the Get Bulk Profile Import Job Profiles endpoint to retrieve successfully imported profiles:

GET /api/profile-bulk-import-jobs/:id/profiles

🚧

Note that the Get Bulk Profile Import Job Profiles endpoint returns the current state of the profiles, not the state at the time that the profiles were imported.

Retrieve related list

Get the list associated with the bulk profile import job with a given job ID via Get Bulk Profile Import Job Lists:

GET /api/profile-bulk-import-jobs/:id/lists

Limitations

Payload limits and job expiration

We enforce the following payload limits:

1. Maximum total payload size of 5 MB.
2. Maximum of 10,000 profiles per job.
3. Maximum individual profile payload size of 500 KB. Note that if this payload size is exceeded, the profile will be dropped from the processing job.

Note that jobs expire after 7 days. If jobs are requested more than 7 days after creation, the request will result in a 404 error. If limit 1 or 2 is exceeded, we will return a 400 error. See Troubleshooting below for more details on errors.

Validation

Some validation happens synchronously, and some asynchronously. For synchronous validation (e.g., email and phone formatting), at most 1 validation error is shown for each profile.

🚧

Note that bulk import profile jobs are not created in the event that there are synchronous errors (i.e., a 400 response). For example, if a batch of 100 profiles contains invalid emails, no bulk import profile job is submitted, and 0 profiles are imported.

Ordering and duplicates

Processing order is not guaranteed. If there are duplicates within a job or across jobs, there is no guarantee that profiles earlier in the array (or in an earlier job) will be processed first. If ordering is important to your application, you can leverage our synchronous Create and Update Profile APIs to guarantee the order, or wait until a batch is completed.

Note that if there are duplicates in a job, that profile will be listed multiple times in the resulting successful profile list (/api/profile-bulk-import-jobs/1/profiles/).

Consent

The Spawn Bulk Profile Import Job endpoint will not update the consent status for profiles. However, you can create/update profiles via this endpoint, retrieve the related profile IDs upserted by the job, and then update those profiles' consent status using the Subscribe Profiles endpoint. Learn more about collecting consent and best practices.

Troubleshooting

Below are error status codes you may encounter with Bulk Profile Import Jobs, including the corresponding reasons for these errors to help you resolve them.

Job processing errors

The following errors may occur during job processing:

• Missing 1 or more identifiers. We need at least one identifier (e.g., email) to process the profile.
• 1 or more invalid emails or phone numbers are provided. Emails must be in a valid format and phone numbers must be an allowable phone number (i.e., country code exists) in E.164 format.
• The profile update would result in a duplicate profile, so the upsert is dropped. This will be included in the import errors.
• The individual profile payload is too large (> 500 KB). Large custom properties are dropped from the profile update until the profile meets the size requirements.

🚧

After receiving a 200 response, all or some profiles may be created (e.g., some duplicate profiles may be dropped in the process). Use the Get Bulk Profile Import Job Errors endpoint to check for specific import errors.

Additional resources

• Collect email and SMS consent via API
• JSON:API filtering
• Getting started with segments