Spiff API (1.0.0)

Download OpenAPI specification:Download

URL: https://spiff.com

Base URL: https://{subdomain}.spiff.com
Default subdomain: app

Imports

Import API for sending data to Spiff. Bulk processes data as jobs.

Get a list of imports

SecuritySignature

Request

path Parameters

company_id

required

string

UUID of the company

Example: e3804275-aba4-4581-ac23-5b195b1a5f52

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Responses

200

Import info

401

Unauthorized

get/api/external_data/{company_id}/imports

Response samples

application/json

{"imports": [{"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"status": "success",
"completed_at": "2022-01-01T00:00:00.000-00:00",
"created_at": "2022-01-01T00:00:00.000-00:00",
"import_action": "upsert",
"import_target": "teams",
"import_errors": ["Error message"
],
"warnings": ["Warning message"
]
}
]
}

Create or delete records

SecuritySignature

Request

path Parameters

company_id

required

string

UUID of the company

Example: e3804275-aba4-4581-ac23-5b195b1a5f52

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json
required

Import action type and data to be processed

import_target required	string The object that will receive the import. Predefined names can be used here, otherwise the applicable object ID should be used. Enum: "object_id" "teams" "sub_teams" "team_members" "plan_assignments" "0a5de148-4864-41f3-bd59-03ee50435e14"
import_action required	string Upsert: find and update an existing record or create one if an existing record isn't found. Delete: only soft deletes the records found by the provided array of external ids. For safety, hard deleting records are done by request. Enum: "upsert" "delete"
payload required	Array of objects list of records
	Array of objects Used to specify the lookup field to for a relationship. When not specified it will default to external_id

Responses

200

Import created

401

Unauthorized

404

Unable to find the object for the import

post/api/external_data/{company_id}/imports

Request samples

Payload

application/json

{"import_target": "0a5de148-4864-41f3-bd59-03ee50435e14",
"import_action": "upsert",
"payload": [{"external_id": "12345",
"name": "Jane Doe",
"email": "jane.doe@company.com"
}
]
}

Response samples

application/json

{"import": {"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"status": "success",
"completed_at": "2022-01-01T00:00:00.000-00:00",
"created_at": "2022-01-01T00:00:00.000-00:00",
"import_action": "upsert",
"import_target": "teams",
"import_errors": ["Error message"
],
"warnings": ["Warning message"
]
}
}

Get the status of an import

SecuritySignature

Request

path Parameters

company_id required	string UUID of the company Example: e3804275-aba4-4581-ac23-5b195b1a5f52
id	string ID of the record or object

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Responses

200

Import info

401

Unauthorized

get/api/external_data/{company_id}/imports/{id}

Response samples

application/json

{"imports": [{"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"status": "success",
"completed_at": "2022-01-01T00:00:00.000-00:00",
"created_at": "2022-01-01T00:00:00.000-00:00",
"import_action": "upsert",
"import_target": "teams",
"import_errors": ["Error message"
],
"warnings": ["Warning message"
]
}
]
}

Test endpoint

SecuritySignature

Request

path Parameters

company_id

required

string

UUID of the company

header Parameters

Signature

required

string^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

company_id

required

string <guid>

Responses

200

The signature header was generated correctly

401

Unauthorized

404

Unable to find the company

post/api/external_data/{company_id}/imports/test

Request samples

Payload

application/json

{"company_id": "0a5de148-4864-41f3-bd59-03ee50435e14"
}

Response samples

application/json

{"success": true
}

Webhooks

Webhook API for upserting or deleting records. Provides instant acceptance/rejection of data, as opposed to job processing.

Upsert a single record

SecuritySignature

Request

path Parameters

mapping_id

required

string

ID of the mapping

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

object

Responses

200

Success

401

Unauthorized

422

Unprocessible entity

put/_webhook/mapping/{mapping_id}

Request samples

Payload

application/json

{"external_id": "12345",
"name": "Jane Doe",
"email": "jane.doe@company.com"
}

Response samples

application/json

{"ok": true
}

Delete a single record

SecuritySignature

Request

path Parameters

mapping_id

required

string

ID of the mapping

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

object

Responses

200

Success

401

Unauthorized

delete/_webhook/mapping/{mapping_id}

Request samples

Payload

application/json

{"external_id": "12345"
}

Response samples

application/json

{"ok": true
}

Upsert multiple records

SecuritySignature

Request

path Parameters

mapping_id

required

string

ID of the mapping

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

arrays

Responses

200

Success

401

Unauthorized

422

Unprocessible entity

put/_webhook/mapping/{mapping_id}/bulk

Request samples

Payload

application/json

[{"external_id": "12345",
"name": "Jane Doe",
"email": "jane.doe@company.com"
},
{"external_id": "67890",
"name": "John Smith",
"email": "john.smith@company.com"
}
]

Response samples

application/json

{"ok": true
}

Delete multiple records

SecuritySignature

Request

path Parameters

mapping_id

required

string

ID of the mapping

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

arrays

Responses

200

Success

401

Unauthorized

delete/_webhook/mapping/{mapping_id}/bulk

Request samples

Payload

application/json

[{"external_id": "12345"
},
{"external_id": "67890"
}
]

Response samples

application/json

{"ok": true
}

Test

Test webhook authentication and formatting, without upserting data.

SecuritySignature

Request

path Parameters

mapping_id

required

string

ID of the mapping

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

object

Responses

200

Success

401

Unauthorized

put/_webhook/mapping/{mapping_id}/test

Request samples

Payload

application/json

{"external_id": "12345",
"name": "Jane Doe",
"email": "jane.doe@company.com"
}

Response samples

application/json

{"ok": true
}

Objects - Alpha

Object API for CRUD operations on objects in Spiff. This is an Alpha release, and may produce unintended results.

Get all objects

SecuritySignature

Request

path Parameters

company_id

required

string

UUID of the company

Example: e3804275-aba4-4581-ac23-5b195b1a5f52

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Responses

200

List of objects and their fields

401

Unauthorized

404

Unable to find the company

get/api/external_data/{company_id}/objects

Response samples

application/json

{"objects": [{"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"label": "User",
"label_plural": "Users",
"record_type": "user",
"source": "manual",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
]
}

Create an object and its fields

SecuritySignature

Request

path Parameters

company_id

required

string

UUID of the company

Example: e3804275-aba4-4581-ac23-5b195b1a5f52

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

Object and its fields

object (ObjectPayload)

Parameters used to create a new object

Responses

200

Object created

401

Unauthorized

404

Unable to find the company

post/api/external_data/{company_id}/objects

Request samples

Payload

application/json

{"object": {"label": "Users",
"record_type": "user",
"source": "salesforce",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Response samples

application/json

{"object": {"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"label": "User",
"label_plural": "Users",
"record_type": "user",
"source": "manual",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Get a single object

SecuritySignature

Request

path Parameters

company_id required	string UUID of the company Example: e3804275-aba4-4581-ac23-5b195b1a5f52
id	string ID of the record or object

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Responses

200

Object and its fields

401

Unauthorized

404

Unable to find the company

get/api/external_data/{company_id}/objects/{id}

Response samples

application/json

{"object": {"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"label": "User",
"label_plural": "Users",
"record_type": "user",
"source": "manual",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Update an objects fields

SecuritySignature

Request

path Parameters

company_id required	string UUID of the company Example: e3804275-aba4-4581-ac23-5b195b1a5f52
id	string ID of the record or object

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Request Body schema: application/json

Object and its fields

object (ObjectPayload)

Parameters used to create a new object

Responses

200

Object fields updated

401

Unauthorized

404

Unable to find the company or object

422

Invalid request

put/api/external_data/{company_id}/objects/{id}

Request samples

Payload

application/json

{"object": {"label": "Users",
"record_type": "user",
"source": "salesforce",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Response samples

application/json

{"object": {"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"label": "User",
"label_plural": "Users",
"record_type": "user",
"source": "manual",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Delete an empty object

SecuritySignature

Request

path Parameters

company_id required	string UUID of the company Example: e3804275-aba4-4581-ac23-5b195b1a5f52
id	string ID of the record or object

header Parameters

Signature

required

string ^t=[0-9]+,v1=[A-Fa-f0-9]{64}$

SHA256 HMAC digest of {TIMESTAMP}.{JSON BODY} using the secret

Example: t=123456789,v1=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Responses

200

Object deleted

401

Unauthorized

404

Unable to find the company or object

422

Invalid request

delete/api/external_data/{company_id}/objects/{id}

Response samples

application/json

{"object": {"id": "0a5de148-4864-41f3-bd59-03ee50435e14",
"label": "User",
"label_plural": "Users",
"record_type": "user",
"source": "manual",
"fields": [{"name": "email",
"data_type": "string",
"required": true
}
]
}
}

Spiff API (1.0.0)

Imports

Get a list of imports

path Parameters

header Parameters

Create or delete records

path Parameters

header Parameters

Request Body schema: application/jsonrequired

Get the status of an import

path Parameters

header Parameters

Test endpoint

path Parameters

header Parameters

Request Body schema: application/json

Webhooks

Upsert a single record

path Parameters

header Parameters

Request Body schema: application/json

Delete a single record

path Parameters

header Parameters

Request Body schema: application/json

Upsert multiple records

path Parameters

header Parameters

Request Body schema: application/json

Delete multiple records

path Parameters

header Parameters

Request Body schema: application/json

Test

path Parameters

header Parameters

Request Body schema: application/json

Objects - Alpha

Get all objects

path Parameters

header Parameters

Create an object and its fields

path Parameters

header Parameters

Request Body schema: application/json

Get a single object

path Parameters

header Parameters

Update an objects fields

path Parameters

header Parameters

Request Body schema: application/json

Delete an empty object

path Parameters

header Parameters

Request Body schema: application/json
required