Salesforce Docs Portal

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.

export COMPANY_UUID="COMPANY_ID"
export SECRET="COMPANY_SECRET"
export URL="https://SUBDOMAIN.spiff.com/api/external_data/$COMPANY_UUID/objects"
export BODY=""
export TIMESTAMP=$(date +%s)
export MESSAGE="${TIMESTAMP}.${BODY}"
export DIGEST=$(printf '%s' "$MESSAGE" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $NF}')
export SIGNATURE="t=${TIMESTAMP},v1=${DIGEST}"
echo "SIGNATURE: $SIGNATURE"

curl -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.

import hashlib
import json
import hmac
import time

secret = b"KEY"

body = {
    "import_target": "OBJECT_ID",
    "import_action": "upsert",
    "payload": [
        {
            "external_id": "12345",
            "name": "Test Person",
            "email": "test.person@example.com"
        }
    ]
}
epoch_timestamp = str(int(time.time()))
json_body = json.dumps(body)
predigeststring = f"{epoch_timestamp}.{json_body}".encode("utf-8")
signatureHash = hmac.new(secret, predigeststring, hashlib.sha256).hexdigest()

headers = {
    "Signature": f"t={epoch_timestamp},v1={signatureHash}",
    "Content-Type": "application/json"
}

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.

curl "https://SUBDOMAIN.spiff.com/api/external_data/COMPANY_ID/imports/test" \
  -X POST \
  -H "signature: t=TIMESTAMP,v1=DIGEST" \
  -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