Get Started with Salesforce Spiff Import API and Object API

Import records into Salesforce Spiff, such as teams and team assignments, or create, read, update, and delete Spiff objects and fields.

1. Generate the HMAC-SHA256 Signature 

All endpoints in the Spiff Import API and Spiff Object 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.

First, contact Salesforce Customer Support and request the secret key for your company. Then, generate the signature.

cURL Example 

Here’s a cURL example for generating a signature.

HMAC-SHA256 signature generation cURL example
1export COMPANY_UUID="COMPANY_ID"
2export SECRET="COMPANY_SECRET"
3export URL="https://SUBDOMAIN.spiff.com/api/external_data/$COMPANY_UUID/objects"
4export BODY=""
5export TIMESTAMP=$(date +%s)
6export MESSAGE="${TIMESTAMP}.${BODY}"
7export DIGEST=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
8export SIGNATURE="t=${TIMESTAMP},v1=${DIGEST}"
9echo "SIGNATURE: $SIGNATURE"
10
11curl -v GET "$URL" -H 'content-type: application/json' -H "Signature: $SIGNATURE"

Replace these values:

  • COMPANY_ID: Your Spiff company ID, which you can find at Admin » Settings » Company Settings » Company Identifiers.
  • COMPANY_SECRET: Your Spiff company secret that you received from Salesforce Customer Support.
  • SUBDOMAIN: The subdomain for your Spiff environment.
    • If you’re in the US, use us1.
    • If you’re in the EU, use eu1.

Python Example 

Here’s a Python example.

HMAC-SHA256 signature generation Python example
1import hashlib
2import json
3import hmac
4import time
5
6secret = b"KEY"
7
8body = {
9    "import_target": "OBJECT_ID",
10    "import_action": "upsert",
11    "payload": [
12        {
13            "external_id": "12345",
14            "name": "Test Person",
15            "email": "test.person@example.com"
16        }
17    ]
18}
19epoch_timestamp = str(int(time.time()))
20json_body = json.dumps(body)
21predigeststring = f"{epoch_timestamp}.{json_body}".encode("utf-8")
22signatureHash = hmac.new(secret, predigeststring, hashlib.sha256).hexdigest()
23
24headers = {
25    "Signature": f"t={epoch_timestamp},v1={signatureHash}",
26    "Content-Type": "application/json"
27}

Replace these values:

  • KEY: Your Spiff company secret that you received from Salesforce Customer Support.
  • OBJECT_ID: The ID of a Spiff object, such as 0a5de148-4864-41f3-bd59-03ee50435e14, or the name of a supported Spiff object, such as teams.

2. Test the Signature 

To verify that you generated the HMAC-SHA256 signature correctly, pass the signature in a header with the testImport endpoint.

1curl "https://SUBDOMAIN.spiff.com/api/external_data/COMPANY_ID/imports/test" \
2  -X POST \
3  -H "signature: t=TIMESTAMP,v1=DIGEST" \
4  -H "content-type: application/json"

Replace these values:

  • SUBDOMAIN: The subdomain for your Spiff environment.
    • If you’re in the US, use us1.
    • If you’re in the EU, use eu1.
  • COMPANY_ID: Your company’s UUID in Spiff, which you can find at Admin » Settings » Company Settings » Company Identifiers.
  • TIMESTAMP: The string representation of the UTC epoch timestamp when the signature was created.
  • DIGEST: The string representation of the HMAC-SHA256 signature that you generated.

You can now use the other endpoints in the Import API and Object API. See Spiff Import API and Spiff Object API. Make sure that you pass the signature header for every endpoint.

See Also

Get Started with Import API and Object API
Get Started with Webhook API
Get Started with Reporting API
Get Started with System Activity Log Export API
API Access for the Spiff Commission Estimator