Skip to main content

Quickstart

This guide lists your workflows, then imports two contacts into one of them.

1. Create an API key​

In Harmony, open Settings > Developers and create a named key. The key starts with harmony_pk_ and is shown once, so store it in your secret manager right away.

The examples below read the key from an environment variable:

export HARMONY_API_KEY="harmony_pk_..."

2. List your workflows​

curl https://api.harmony.ai/api/v1/workflows \
  -H "Authorization: Bearer $HARMONY_API_KEY"

The response is a page of workflows:

{
  "data": [
    {
      "id": "0196f0a2-8c1e-7b3a-9d41-2f6e5a7c8b90",
      "name": "Inbound demo requests",
      "status": "published"
    }
  ],
  "nextToken": null
}

Copy the id of the workflow you want to enroll contacts into. Responses contain more fields than shown here; the API reference documents all of them.

3. Import contacts​

curl https://api.harmony.ai/api/v1/contacts/bulk \
  -H "Authorization: Bearer $HARMONY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignmentOptions": { "workflowId": "0196f0a2-8c1e-7b3a-9d41-2f6e5a7c8b90" },
    "contacts": [
      { "sourceKind": "api", "externalId": "crm-1001", "firstName": "Dana", "phone": "+12125550198" },
      { "sourceKind": "api", "externalId": "crm-1002", "firstName": "Lee", "phone": "+12125550199" }
    ]
  }'

Harmony answers 202 Accepted with the number of contacts it queued:

{ "accepted": 2 }

Contacts are created a few seconds later, and the workflow calls them during the workflow's calling hours.

4. Check the result​

curl "https://api.harmony.ai/api/v1/contacts?searchTerm=Dana" \
  -H "Authorization: Bearer $HARMONY_API_KEY"

The same calls in TypeScript​

const response = await fetch("https://api.harmony.ai/api/v1/workflows", {
  headers: { Authorization: `Bearer ${process.env.HARMONY_API_KEY}` },
});

if (!response.ok) {
  throw new Error(`Harmony API ${response.status}: ${await response.text()}`);
}

const { data, nextToken } = await response.json();

Use https://api.eu.harmony.ai if your Account is in the EU region. See Environments.