The Catalyst public API is a simple, secure, JSON-based interface for viewing customer business data on the Catalyst platform in a programmatic way.
The Catalyst API is intended for software developers. To use it you should be familiar with web programming and be comfortable creating applications that consume web services through HTTP requests.
What you should know
- Create secure API keys to access endpoints
- There is a global rate limit of 100 calls per minute, per customer instance
- For the OpenAPI specification, please refer to our public API documentation
- Refer below to data definitions for API endpoints
Data definitions for API endpoints
Account Data & Health Scores
| Label Name | Description | API Endpoints | Attribute Path |
| Account ID | The account's unique Catalyst ID | GET /accounts | "Data" > "id" |
| External ID | The account's unique Salesforce ID | GET /accounts/{account_id} | "Data" > "external_id" |
| Created At | When the Catalyst account record was created | GET /accounts/{account_id} | "Data" > "created_at" |
| Updated At | When the Catalyst account record was last updated | GET /accounts/{account_id} | "Data"> "updated_at" |
| Account Name | The account's Name in Catalyst & Salesforce | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Account Type | The account's Type field (from Salesforce) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Description | The account’s Description field (from Salesforce) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Health | The account’s Catalyst Health category ("Healthy", "Neutral" or "At-Risk") | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Industry | The account’s Industry field (from Salesforce) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Numerical Health Score | The account’s Catalyst Numeric Health score (1-10 score decimal) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Phone | The account’s Phone field (from Salesforce) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
| Website | The account’s Website field (from SFDC) | GET /accounts/{account_id} | "Data" > "attributes" > "label", "value" |
Account Health Groups & Inputs Scores
| Label Name | Description | API Endpoints | Attribute Path |
| Health Group ID | The account's Health Score Group ID |
GET /accounts/{account_id} /health_groups |
"Data" > "group_id" |
| Health Group Name | The Health Group Name (up to 5 Groups, each has a weighting of Inputs to calculate Health Score) |
GET /accounts/{account_id} /health_groups |
"Data" > "name" |
| Health Group Description | The Health Group Description |
GET /accounts/{account_id} /health_groups |
"Data" > "description" |
| Health Group Score | The Health Group Score (1-10 score decimal) |
GET /accounts/{account_id} /health_groups |
"Data" > "group_score" |
| Health Group Weight | The weight of the Health Group as it pertains to the overall Health Score calculation |
GET /accounts/{account_id} /health_groups |
"Data" > "weight" |
| Health Group Updated At | When the Health Group was last updated at |
GET /accounts/{account_id} /health_groups |
"Data"> "updated_at" |
| Health Profile ID | The Health Profile ID the Heath Group is a part of |
GET /accounts/{account_id} /health_groups |
"Data" > "health_profile" > "id" |
| Health Profile Name | Health Profile Name (Multiple Health Scores can be configured with each configuration labeled as a "Profile" - e.g., you may create 3 different profiles for SMB, MM and Enterprise accounts respectively) |
GET /accounts/{account_id} /health_groups |
"Data" > "health_profile" > "name" |
| Health Input Score | The individual Input’s Score (1-10 score decimal) |
GET /accounts/{account_id} /health_groups |
"Data" > "health_inputs" > "score" |
| Health Input Field Name | Input Field Name (a health score can have an unlimited number of fields, the field is scored on a scale of 1-10 and rolls up to an overall group score, that then rolls into the overall health score) |
GET /accounts/{account_id} /health_groups |
"Data" > "health_inputs" > "field_name" |
Playbook Data & Overall Performance
| Label Name | Description | API Endpoints | Attribute Path |
| Playbook ID | The unique ID for the playbook | GET /playbooks | "Data" > "id" |
| Playbook Name | Name of the playbook | GET /playbooks/{playbook_id} | "Data" > "name" |
| Playbook Status | Status of the playbook (enabled, paused, disabled) | GET /playbooks/{playbook_id} | "Data" > "status" |
| Current Participants | How many object records are currently running through the playbook | GET /playbooks/{playbook_id} | "Data" > "current_participants_count" |
| Total Participants | How many object records have run in this playbook | GET /playbooks/{playbook_id} | "Data" > "total_participants_count" |
| Met Objective Impact | The percentage of participants who successfully met the playbook objective within 30 days of exiting the playbook. | GET /playbooks/{playbook_id} | "Data" > "met_objective_percentage" |
| Average Objective Impact | The average change in the playbook objective metric across all participants (%) | GET /playbooks/{playbook_id} | "Data" > "avg_objective_percentage _change" |
| Object Type | The object type this playbook built for (account, opportunity, etc.) | GET /playbooks/{playbook_id} | "Data” > “object_type” |
| Created At | When the playbook was created | GET /playbooks/{playbook_id} | “Data" > "created_at" |
| Updated At | When was the playbook was last updated | GET /playbooks/{playbook_id} | "Data" > "updated_at" |
| Creator Name | Which user created the playbook | GET /playbooks/{playbook_id} | "Data" > "created_by" > "name" |
Playbook Run Performance
| Label Name | Description | API Endpoints | Attribute Path |
| Playbook ID | The unique ID for the playbook | GET /playbooks | "Data" > "id" |
| Playbook Name | The name of the playbook | GET /playbooks/{playbook_id} | "Data" > "name" |
| Run ID | The unique ID for this playbook run |
GET /playbooks/{playbook_id} /executions |
"Data" > "id" |
| Status | What is the status of the run (still in the playbook, completed, etc.) |
GET /playbooks/{playbook_id} /executions |
"Data”"> "status" |
| Enter Type | How did the object enter the playbook (i.e. "Manual" or "Automatic") |
GET /playbooks/{playbook_id} /executions |
"Data" > "enter_type" |
| Enter Date | Date of object record entry into playbook |
GET /playbooks/{playbook_id} /executions |
"Data" > "enter_date" |
| Exited Date | Date of object record exiting the playbook |
GET /playbooks/{playbook_id} /executions |
"Data" > "exited_date" |
| Days in Playbook | How long was this object record is in playbook |
GET /playbooks/{playbook_id} /executions |
"Data" > "days_in_playbook" |
| Object Record ID | The unique Catalyst ID for the object record that entered the playbook (an object record can re-enter the same playbook multiple times) |
GET /playbooks/{playbook_id} /executions |
"Data" > "object" > "id" |
| Object External ID | The object record’s unique Salesforce ID |
GET /playbooks/{playbook_id} /executions |
"Data" > "object" > "external_id" |
| Object Type | Object record type entered into the playbook (account, contact, opportunity, additional object) |
GET /playbooks/{playbook_id} /executions |
"Data" > "object" > "type" |
| Objective Value on Entry | The objective field value when the customer entered the playbook |
GET /playbooks/{playbook_id} /executions |
"Data" > "objective" > "objective_value_on_entry" |
| Objective Value on Exit | The objective field value when the customer exited the playbook |
GET /playbooks/{playbook_id} /executions |
"Data" > "objective" > "objective_value_on_exit" |
| Objective Met | Was the objective met (TRUE or FALSE) |
GET /playbooks/{playbook_id} /executions |
"Data” > "objective" > "objective_met" |
| Objective Met Date | What date did the customer meet the objective |
GET /playbooks/{playbook_id} /executions |
"Data” > "objective" > "objective_met_date" |
| Objective Value on Day 30 Day | What was the objective value 30 days after the customer exited the playbook |
GET /playbooks/{playbook_id} /executions |
"Data” > "objective" > "objective_value_on_day _thirty" |
| Added By | If the object record Playbook enter type is “Manual”, user name of who added them |
GET /playbooks/{playbook_id} /executions |
"Data" > "Added By" > "name" |
Playbook Emails
| Label Name | Description | API Endpoints | Attribute Path |
| Playbook ID | The unique ID for the playbook (the playbook associated with the email) | GET /playbooks | "Data" > "id" |
| Playbook Name | The name of the playbook (the playbook that created the email) | GET /playbooks/{playbook_id} | "Data" > "name" |
| Email ID | An ID representing a unique email that is sent. There will be one row per email recipient. |
GET /playbooks/{playbook_id} /executions |
"Data" > "emails" > "id" |
| Email Subject | The subject of the sent email (this may be null if the email has not been approved for send) | GET /emails/{email_id} | "Data" > "subject" |
| Email Automated | If the email was sent automatically from a playbook (TRUE or FALSE) | GET /emails/{email_id} | "Data" > "automated" |
| Email Sent At | Timestamp for when the email was sent | GET /emails/{email_id} | "Data" > "sent_at" |
| Email Approved At | Timestamp for when the email was approved in Catalyst for sending | GET /emails/{email_id} | "Data" > "approved_at" |
| Email Rejected At | Timestamp for when the email was rejected in Catalyst for sending | GET /emails/{email_id} | "Data" > "rejected_at" |
| Email Status | Status of the email (sent, rejected, awaiting approval) | GET /emails/{email_id} | "Data" > "status" |
| Recipient Email | The email address of the recipient of the email (this may be null if the email is not yet approved) | GET /emails/{email_id} | "Data" > "recipient" > "email" |
| Email Recipient First Clicked At | The first time the recipient of the email clicked a link in the email (this data may be missing if the recipient has trackers blocked) | GET /emails/{email_id} | "Data" > "recipient" > "first_clicked_at" |
| Email Recipient Last Clicked At | The last time the recipient of the email clicked a link in the email (this data may be missing if the recipient has trackers blocked) | GET /emails/{email_id} | "Data" > "recipient" > "last_clicked_at" |
| Email Recipient First Opened At | The first time the recipient of the email opened the email (this data may be missing if the recipient has trackers blocked) | GET /emails/{email_id} | "Data" > "recipient" > "first_opened_at" |
| Email Recipient Last Opened At | The last time the recipient of the email opened the email (this data may be missing if the recipient has trackers blocked) | GET /emails/{email_id} | "Data" > "recipient" > "last_opened_at" |
| Email Recipient Bounced At | The time this email bounced from the recipient. In an instance where Sendgrid retries, it's possible to both bounce and be delivered | GET /emails/{email_id} | "Data" > "recipient" > "bounced_at" |
| Sender Name | Name of the sender of the email | GET /emails/{email_id} | "Data" > "sender" > "name" |
| Sender Email | Email address the email appears to have come from (this may be a default Catalyst email or the customer may provide a whitelisted domain) | GET /emails/{email_id} | "Data" > "sender" > "email" |
Playbook Email Template Performance
| Label Name | Description | API | Endpoint |
| Template ID | The playbook email template's unique ID |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "id" |
| Email Subject | The playbook email template's subject line |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "subject" |
| Template Created At | Timestamp for when the playbook email template was created |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "created_at" |
| Template Updated At | Timestamp for when the playbook email template was last updated |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "updated_at" |
| Delivered Rate | The total rate for which an email is delivered to all end recipients (decimal ratio) |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "performance" > "delivered_rate" |
| Not Delivered Rate | The total rate for which an email is not delivered to all end recipients (decimal ratio) |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "performance" > "not_delivered_rate" |
| Opened Rate | The total rate for which an email is opened by all end recipients (decimal ratio) |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "performance" > "opened_rate" |
| Clicked Rate | The total rate for which an email is clicked by all end recipients (decimal ratio) |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "performance" > "clicked_rate" |
| Replied Rate | The total rate for which an email is replied to by all end recipients (decimal ratio) |
GET /playbooks/{playbook_id} /email_templates |
"Data" > "performance" > "replied_rate" |