--- schema_version: "1" id: a5dcded949ebb0d28d6ab9dbb022b0d021c59d42890c5d463825c0d82df63ac7 title: Spiff Import API collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/sales-cloud/spiff/references/generated-api-specs/spiff-import-api-reference.md canonical_url: https://developer.salesforce.com/docs/sales/spiff/references/spiff-import-api-reference source_site: developer.salesforce.com content_type: documentation content_hash: d54bc8a97536f08cc1fc1c6b5d699897bc2fc63b4988247f1024f07f3a72c939 products: - Salesforce Spiff - Sales Cloud --- Spiff Import API # Spiff Import API Create or delete records for Salesforce Spiff objects, such as teams and team assignments. All endpoints in the Spiff Import API require a signature header, which is a HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. For information about generating the signature header, see [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). **Version:** 1.0.0 ## Servers * `https://{subdomain}.spiff.com/api/external_data` Default security: signature. ## Security * `signature` (apiKey) HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. See [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). * API key in header: signature ## Operations ### GET getListOfImports `GET /{company_id}/imports` Operation ID: `getListOfImports`. Returns a list of all imported records. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `company_id` (path, string (guid), required) Your company's UUID in Spiff, which you can find at **Admin » Settings » Company Settings » Company Identifiers**. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. See [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Responses * **200** The request was successful. The response includes the list of imported records. Media type: `application/json`. Schema: `object`. * `imports` (_array of Import_) * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * Your import format is invalid. * Your import format doesn't match your connector fields. * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. ### POST createOrDeleteRecords `POST /{company_id}/imports` Operation ID: `createOrDeleteRecords`. Creates or deletes records for a target Spiff object. **Tip:** To see examples for creating and deleting records for specific objects, scroll to the _Body_ section of this page and select an example from the dropdown. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `company_id` (path, string (guid), required) Your company's UUID in Spiff, which you can find at **Admin » Settings » Company Settings » Company Identifiers**. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. See [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body (required) Values for the records that you want to import. Media type: `application/json`. Schema: `ImportPayload`. _Example: import\_user_ users ``` { "import_target": "0a5de148-4864-41f3-bd59-03ee50435e14", "import_action": "upsert", "payload": [ { "external_id": "12345", "name": "Jane Doe", "email": "jane.doe@company.com" } ] } ``` _Example: import\_plan\_assignment_ plan\_assignments ``` { "import_target": "plan_assignments", "import_action": "upsert", "payload": [ { "external_id": "plan_assignment_123", "plan_internal_id": "e0d03c72-d150-4e91-af56-77d2a1278254", "plan_name": "SDR Plan", "effective_as_of": "2022-01-01", "effective_until": "2022-12-31", "user_id": "A12345", "OTE": 150000 } ] } ``` _Example: import\_team\_member_ team\_members ``` { "import_target": "team_members", "import_action": "upsert", "payload": [ { "external_id": "team_assignment_primary_key", "team_external_id": "east_region_team_primary_key", "effective_as_of": "2022-04-01", "effective_until": "2022-06-30", "user_id": "A12345", "is_manager": false } ], "foreign_keys": [ { "normalized_object": "user", "lookup_field": "WorkdayId" } ] } ``` _Example: import\_team_ teams ``` { "import_target": "teams", "import_action": "upsert", "payload": [ { "external_id": "east_region_team_primary_key", "name": "East Region", "custom_values": [ { "name": "Team_Quota", "type": "integer", "value": 1000000 } ] } ] } ``` _Example: import\_sub\_team_ sub\_teams ``` { "import_target": "sub_teams", "import_action": "upsert", "payload": [ { "external_id": "subteam_assignment_primary_key", "parent_team_external_id": "us_region_team", "sub_team_external_id": "east_region_team_primary_key", "effective_as_of": "2022-01-01", "effective_until": "2022-12-31" } ] } ``` #### Responses * **200** The request was successful and the import was created. Media type: `application/json`. Schema: `object`. * `import` (_Import_) * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * Your import format is invalid. * Your import format doesn't match your connector fields. * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. * **404** The request was unsuccessful because Spiff couldn't find the object to import records for. ### GET getSingleImport `GET /{company_id}/imports/{id}` Operation ID: `getSingleImport`. Returns a summary of a specific import job. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `company_id` (path, string (guid), required) Your company's UUID in Spiff, which you can find at **Admin » Settings » Company Settings » Company Identifiers**. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. See [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. * `id` (path, string, required) The ID of an import job. #### Responses * **200** The request was successful. The response includes details about the import job. Media type: `application/json`. Schema: `object`. * `imports` (_array of Import_) * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * Your import format is invalid. * Your import format doesn't match your connector fields. * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. ### POST testImport `POST /{company_id}/imports/test` Operation ID: `testImport`. Tests the HMAC-SHA256 signature authentication, but doesn't upsert or delete any data. The request body must be an empty JSON object. #### Parameters * `subdomain` (path, string, required) The subdomain for your Spiff environment. * If you're in the US, use `us1`. * If you're in the EU, use `eu1`. _Example_ ``` us1 ``` * `company_id` (path, string (guid), required) Your company's UUID in Spiff, which you can find at **Admin » Settings » Company Settings » Company Identifiers**. _Example_ ``` e3804275-aba4-4581-ac23-5b195b1a5f52 ``` * `signature` (header, string, required) HMAC-SHA256 cryptographic hash of the current time, the request body, and a secret key for your company. The signature format is `t={timestamp},v1={digest}`, where `{timestamp}` is a UTC epoch timestamp and `{digest}` is a string representation of the HMAC-SHA256 digest. See [Get Started with Salesforce Spiff Import API and Object API](/docs/sales/spiff/guide/import-object-api-get-started.html). Example: `t=1750092638,v1=d79efcece486e8de2f0384b9b07f2af6cd5859685489f6c1fd71be`. #### Request body An empty JSON object. Media type: `application/json`. Schema: `object`. _Example_ ``` {} ``` #### Responses * **200** The request was successful and the HMAC-SHA256 signature was generated correctly. Media type: `application/json`. Schema: `object`. * `success` (_boolean_) Example: `true`. * **400** The request was unsuccessful for one of these reasons: * Your endpoint URL is invalid. * Your import format is invalid. * Your import format doesn't match your connector fields. * **401** The request was unsuccessful because the HMAC-SHA256 signature is invalid. * **404** The request was unsuccessful because we couldn't find a match for the `company_id`. ## Schemas ### Import Represents metadata for an import job. * `id` (_string (guid)_) The ID of the Spiff object that you're importing records for. Example: `0a5de148-4864-41f3-bd59-03ee50435e14`. * `status` (_string_) The status of the import job. Allowed values: `queued`, `processing`, `succeeded`, `aborted`, `failed`, `partially_succeeded`. Example: `success`. * `completed_at` (_string_) The date and time when the import job finished. Example: `2022-01-01T00:00:00.000-00:00`. * `created_at` (_string_) The date and time when the import job began. Example: `2022-01-01T00:00:00.000-00:00`. * `import_action` (_string_) The operation that the import job performed. Allowed values: `upsert`, `delete`. Example: `upsert`. * `import_target` (_string_) The object that you're importing records for. For some supported system objects, specify the object name: `teams`, `sub_teams`, `team_members`, or `plan_assignments`. Otherwise, specify the ID of a webhook object or an object that you created. Records for other system objects or for objects that you sync with a Salesforce connector can't be imported. Allowed values: `OBJECT_ID`, `teams`, `team_members`, `user`, `plan_assignment`. Example: `teams`. * `import_errors` (_array of string_) A list of errors that occurred during the import job. Items: Example: `Error message`. * `warnings` (_array of string_) A list of warnings that occurred during the import job. Items: Example: `Warning message`. ### ImportPayload Represents the Spiff records that you're upserting or deleting. * `import_target` (_string_, required) The object that you're upserting or deleting records for. For some supported system objects, specify the object name: `teams`, `sub_teams`, `team_members`, or `plan_assignments`. Otherwise, specify the ID of a webhook object or an object that you create. You can't upsert or delete records for other system objects or for objects that you sync with a Salesforce connector. Allowed values: `OBJECT_ID`, `teams`, `sub_teams`, `team_members`, `plan_assignments`. * `import_action` (_string_, required) The operation that the import job performed. The `upsert` operation finds and updates records that match `payload`. If a matching record doesn't exist, the record is created. The `delete` operation soft-deletes records that match `payload`. To delete records permanently, contact Salesforce Customer Support. Allowed values: `upsert`, `delete`. * `payload` (_array of object_, required) The records that you want to upsert or delete. When `import_target` is `plan_assignments`, make sure that `payload` includes either `plan_name` or `plan_internal_id`. Only one of these values is required. If you provide both values, `plan_internal_id` takes priority. * `foreign_keys` (_array of object_) The identifiers in an external system that Spiff uses for validating records in `payload`. This property is used only when `import_target` is `team_members`. When this property is specified, Spiff references these foreign keys instead of the default primary key field when validating user records. Typically, the default primary key field is `external_id`. * `normalized_object` (_string_) The normalized Spiff object table that you're importing records to. This value must be `users`. Example: `user`. * `lookup_field` (_string_) The field in the external system that contains the foreign key value that you want to reference. Example: `WorkdayId`.