PivotCX Webhook Integration Guide

Table of Contents:

Changes:

Revision .6 (August, 9, 2023)

Added apply URL to from form webhook

Revision 0.5 (November 30, 2022):

Added delivery callback documentation Added attachment callback documentation Added webform support documentation

Revision 0.4 (February 3, 2022):

Added support for requisition IDs in HROS spec in Appendix A

Revision 0.4 (March 17, 2021):

Added blast webhook. You can now supply a list of contacts and send a templated message to all of them.

Added support for adding a custom message to new job applications.

Revision 0.3 (February 2, 20201):

You can now provide attribution data including source, alternate job titles, campaign, and location when sending candidates to

About PivotCX

PivotCX is the communication hub for talent acquisition. PivotCX makes it easy to automate, coordinate and communicate across multiple channels including:

  • Voice
  • SMS
  • One-to-One Video

Web

When integrated with job boards, applicant tracking systems, CRMs, career websites, and integration platforms, PivotCX makes it possible to automate many routine communications and drive unprecedented levels of recruiter productivity.

Getting A Sandbox Instance

If you’d like to integrate your app with PivotCX, contact our partnerships team and request access here.

Integration Method

PivotCX uses webhooks where you POST a JSON or HTTP multi-part form formatted payload.

PivotCX can call back your webhook or API endpoint and deliver message receipts that confirm message delivery (or error state) and a conversation wrap-up that includes the status (e.g. “screened out” or “approved”) and a summary of the chat agent’s conversation.

Webhooks

send_application Allows a contact including job application and marketing attribution to be sent to PivotCX. An optional message can be included that will be sent to the applicant immediately, or at a scheduled time.

blast Allows a list of contacts and message template to be sent to PivotCX. The message will be sent now, or at a scheduled time.

The send_application Webhook

send_application Workflow

  1. The candidate applies for a job or fills in a contact form.
  1. POST candidate and job data to PivotCX webhook.
  1. PivotCX sends the initial chat message to the candidate and a conversation with a live person. During the conversation, the candidate is usually sold the employment opportunity and qualified.
  1. When a conversation is “wrapped up”, PivotCX can call the ATS back and POST details of the interaction including the status of the conversation, allowing your ATS to continue automated processing of the application.

send_application Webhook Details

POST url:

https://api.pivotcx.io/webhooks/{vendor_name}/send_application/?secret={vendor_shared_secret}&uuid={team_uuid}

{vendor_name} is your PivotCX vendor name.

{vendor_shared_secret} is your PivotCX vendor shared secret

{team_uuid} is the PivotCX UUID for the account (usually a shared customer) where you want to send the candidate.

Body:

Can be in any of three formats:

HTTP form multipart

This is the same format that most web pages use to send form data to the server. It contains data in a key: value format. PivotCX can map your HTTP form multipart payload to our schema.

JSON

PivotCX can accept any JSON payload, and we can map your JSON format to our schema.

HROS JSON

(Contains a Candidate and Job Post in HROS (HR Open Standards JSON) format) See Appendix I for more information on HROS format.

If you need to submit data in a different format, please send an example to your PivotCX representative.

send_application Response

On successful POST, the response is: 200 OK

Standard HTML error codes are returned for failed POSTS.

Callbacks

PivotCX can post the following data when certain events occur:

  • Candidate is delivered or a conversation is wrapped up. Ideal for situation where you want to include a conversation in history in an ATS or HRIS.
  • Attachment is Received

Candidate is Delivered / Conversation Wrap-Up

💡
Note: PivotCX can deliver data to your system in any format, using your schema. If you need custom webhooks, let your PivotCX representative know, or contact us online.

Example Webhook Payload

{
    "contact": {
        "documentId": {"value": "unique_id_for_post", "schemeId": "Partner_name"},
        "uri": "https://www.jobboard.com/44k5jnw23kln",
        "person": {
            "id": {
                "value": "Condidate_id",
                "schemeId": "partner_name",
                "schemeAgencyId": "agency_name(optional)",
            },
            "name": {"formattedName": "John Smith"},
            "communication": {
                "email": [
                    {"address": "smith@mail.com", "useCode": "private", "preference": 1}
                ],
                "phone": [
                    {
                        "useCode": "private",
                        "preference": 1,
                        "formattedNumber": "+13175554444",
                    }
                ],
            },
        },
        "profiles": [
            {
                "profileId": {"value": "4w247145ghad", "schemeId": "YourATS"},
                "attachments": [
                    {
                        "id": {"value": "Resume"},
                        "content": {
                            "value": "UEsDBBQABgAIAAAAIQCidL",
                            "encoding": "base64",
                            "filename": "resume.pdf",
                            "mimeType": "application/pdf",
                        },
                    }
                ],
                "profileName": "Main profile",
                "languageCode": "en-US",
                "associatedPositionOpenings": [
                    {
                        "positionUri": "https://www.jobboard.com/44k5jnw23kln",
                        "positionTitle": "Hiring Manager",
                        "positionCompany": "Your Company",
                        "positionLocation": "US-IN-Fort Wayne",
                        "positionDescriptionHTML": "Job Description HTML",
                        "positionDescriptionText": "Job Description in plain text",
                        "positionDescriptionMarkdown": "Job Description in Markdown",
                        "candidateAppliedIndicator": true,
                    }
                ],
            }
        ],
    },
    "content": {
        "associatedPositionOpenings": [
            {
                "positionUri": "https://www.jobboard.com/44k5jnw23kln",
                "positionTitle": "Hiring Manager",
                "positionCompany": "Your Company",
                "positionLocation": "US-IN-Fort Wayne",
                "positionDescriptionHTML": "Job Description HTML (optional) no link 
                                               (a), table, iframe or script tags) …",
                "positionDescriptionText": "Job Description in plain text (optional)",
                   "positionDescriptionMarkdown": "Job Description in Markdown
                                                  (optional) (links and tables not       
                                                  supported) …",
                “callbackUrl”: “https://www.jobboard.com/44k5jnw23kln/callback/”,
                "candidateAppliedIndicator": true,
            }
        ]
    },
    "conversation": {
        "uuid": "uuid4",
        "wrap_up": {
            "status": "open, closed, review, qualified, not qualified",
            "reason": "justification for status",
            "notes": "Notes from chat agent",
            "sent_to": ["mailto:test@email.com", "tel:+13171231234", "post_url"],
        },
        "transcript": [
            {
                "timestamp": "2021-01-06T14:57:32Z",
                "to": "+13171231234",
                "from": "+131744444144",
                "message_type": "event" or "chat",
                "message": "The message content",
            },
        ],
    },
}

Attachment Received

PivotCX can call your webhook whenever a file attachment is sent via MMS (multimedia text message) or web upload is used. We reflect your job application ID, requisition ID, and contact id if known.

Example Payload

{
  "job_application_attachment_data": {
    "attachment_data": {
      "hash": "",
      "comment": "",
      "created": "2022-11-07T18:34:25.292601+00:00",
      "filename": "chat_transcript_ee5a4845.txt",
      "mime_type": "",
      "file_content": "Encoded file content"
    },
    "contact_reference": {
      "id": {
        "name": "1234",
        "type": "your identifier"
      },
    "job_application_reference": {
      "id": {
        "name": "1234",
        "type": "your identifier"
      },
      "name": "Inclusion Specialist",
      "event": "delivery",
      "medium": "chat",
      "source": "PivotCX",
      "status": "Delivered",
      "campaign": "",
      "location": "HQ"
    },
    "job_requisition_reference": {
      "id": {
        "name": "1234",
        "type": "your identifier"
      },
      "name": "Inclusion Specialist"
    }
  }
}

blast Webhook

Blasts allow you to send messages to one or more contacts. Blasts are ideal for re-engagement of existing ATS contacts.

blast Workflow

  1. POST to the blast webhook.
  1. On success, the UUID of the blast will be returned.
  1. When messages are sent, we will post the result of each message to your message callback URL (this is an integration-level setting).

Blast Webhook Details

POST url:

https://api.pivotcx.io/webhooks/{vendor_name}/blast/?secret={vendor_shared_secret}&uuid={team_uuid}

{vendor_name} is your PivotCX vendor name.

{vendor_shared_secret} is your PivotCX vendor shared secret

{team_uuid} is the PivotCX uuid for the account (usually a shared customer) where you want to send the candidate.

Body:

Contains blast record, a list of candidates in HROS format, and the message to send. Messages may contain template variables (see Appendix III) :

{
  "blast": {
    "name": "Outreach campaign 12.20",
    "sendAt": "Now or 2021-07-16T19:20-05:00",
    "messageText": "$firstname(Hey there) - You applied to $title(a great job) at $teamname. Are you able to chat now? It will take 5-10 minutes?"
  },
  "listName": "OutReach Campaign 12.20",
  "list": ["optional list of contact ids", "uuid1", "uuid2", "uuid3"],
  "contacts": [
    {
      "documentId": {
        "value": "unique_id_for_post",
        "schemeId": "Partner_name"
      },
      "uri": "https://www.jobboard.com/44k5jnw23kln",
      "person": {
        "id": {
          "value": "Candidate_id",
          "schemeId": "partner_name",
          "schemeAgencyId": "agency_name(optional)"
        },
        "name": {
          "formattedName": "John Smith"
        },
        "communication": {
          "email": [
            {
              "address": "smith@mail.com",
              "useCode": "private",
              "preference": 1,
              "optIn": {
                "ipAddress": "124.122.9.123",
                "method": "job apply or form submit"
              }
            }
          ],
          "phone": [
            {
              "useCode": "private",
              "preference": 1,
              "formattedNumber": "+13175554444",
              "optIn": {
                "ipAddress": "124.122.9.123",
                "method": "job apply or form submit"
              }
            }
          ]
        }
      },
      "profiles": [
        {
          "profileId": {
            "value": "4w247145ghad",
            "schemeId": "YourATS"
          },
          "attachments": [
            {
              "id": {
                "value": "Resume"
              },
              "content": {
                "value": "UEsDBBQABgAIAAAAIQCidL... (must be base64 encoded)",
                "encoding": "base64",
                "filename": "resume.pdf",
                "mimeType": "application/pdf"
              }
            }
          ],
          "profileName": "Main profile",
          "languageCode": "en-US",
          "associatedPositionOpenings": [
            {
              "positionUri": "https://www.jobboard.com/44k5jnw23kln",
              "positionTitle": "Hiring Manager",
              "positionCompany": "Your Company",
              "positionLocation": "US-IN-Fort Wayne",
              "positionDescriptionHTML": "Job Description HTML (optional) (no link (a), table, iframe or script tags) …",
              "positionDescriptionText": "Job Description in plain text (optional)",
              "positionDescriptionMarkdown": "Job Description in Markdown (optional) (links and tables not supported) …",
              "callbackUrl": "https://www.jobboard.com/44k5jnw23kln/callback/",
              "candidateAppliedIndicator": true
            }
          ],
          "attribution": {
            "source": "optional. name of source e.g. indeed, Facebook or jobs.com",
            "content": "optional. job variant name or blank",
            "campaign": "optional. name of the campaign or blank",
            "location": "optional. job location name if different than PositionLocation"
          }
        }
      ]
    }
  ]
}

blast Response

On successful POST, the response is 200 OK. The body will contain the uuid of the blast.

Appendix I HR Open Standards (HROS) JSON Format

For more information on HR Open Standards, the global standard for HR data interchange, go to https://www.hropenstandards.org/

💡
Note: PivotCX can accept candidate and job data in any format, using your schema. If you need custom webhooks, let your PivotCX representative know, or contact us online.

Example:

{
  "documentId": {
    "value": "unique_id_for_post",
    "schemeId": "Partner_name"
  },
  "uri": "https://www.jobboard.com/44k5jnw23kln",
  "person": {
    "id": {
      "value": "Unique ID for the candidate (use email address if you don't have an ID)",
      "schemeId": "partner_name",
      "schemeAgencyId": "agency_name(optional)"
    },
    "name": {
      "formattedName": "John Smith"
    },
    "communication": {
      "email": [
        {
          "address": "smith@mail.com",
          "useCode": "private",
          "preference": 1,
          "optIn": {
            "ipAddress": "124.122.9.123",
            "method": "job apply or form submit"
          }
        }
      ],
      "phone": [
        {
          "useCode": "private",
          "preference": 1,
          "formattedNumber": "+13175554444",
          "optIn": {
            "ipAddress": "124.122.9.123",
            "method": "job apply or form submit"
          }
        }
      ]
    }
  },
  "profiles": [
    {
      "profileId": {
        "value": "4w247145ghad",
        "schemeId": "YourATS"
      },
      "attachments": [
        {
          "id": {
            "value": "Resume"
          },
          "content": {
            "value": "UEsDBBQABgAIAAAAIQCidL... (must be base64 encoded)",
            "encoding": "base64",
            "filename": "resume.pdf",
            "mimeType": "application/pdf"
          }
        }
      ],
      "profileName": "Main profile",
      "languageCode": "en-US",
      "associatedPositionOpenings": [
        {
          "PositionOpeningId": {
            "value": "Req ID or Job Post id",
            "schemeId": "YourATS"
          },
          "positionUri": "https://www.jobboard.com/44k5jnw23kln",
          "positionTitle": "Hiring Manager",
          "positionCompany": "Your Company",
          "positionLocation": "US-IN-Fort Wayne",
          "positionDescriptionHTML": "Job Description HTML (optional) (no link (a), table, iframe or script tags) …",
          "positionDescriptionText": "Job Description in plain text (optional)",
          "positionDescriptionMarkdown": "Job Description in Markdown (optional) (links and tables not supported) …",
          "callbackUrl": "https://www.jobboard.com/44k5jnw23kln/callback/",
          "candidateAppliedIndicator": true
        }
      ],
      "attribution": {
        "applicationId": "Unique id for applicant",
        "source": "optional. name of source e.g. indeed, facebook or jobs.com",
        "content": "optional. job variant name or blank",
        "campaign": "optional. name of the campaign or blank",
        "location": "optional. job location name if different than PositionLocation"
      },
      "message": {
        "messageText": "$firstname(Hey there) - You applied to $title(a great job) at $teamname. Are you able to chat now? It will take 5-10 minutes?",
        "afterHoursText": "$firstname(Hey there) - You've applied to $title. It's after hours. Can we chat when I'm back in the office?",
        "repeatApplyText": "$firstname(Hey there) - You've applied to $title. Great to see you again. Are you able to chat now? It will take 5-10 minutes?",
        "sendAt": "Now or 2021-07-16T19:20-05:00",
        "callbackUrl": "optional url. https://www.jobboard.com/44k5jnw23kln/messages"
      }
    }
  ]
}

Appendix II: HTTP Forms

PivotCX can ingest form data in JSON or HTTP form multipart format. PivotCX can map our schema to match your form. PivotCX automatically recognizes the following fields:

job_title

req_id

id

job_id

phone

email

source

medium

campaign

keyword

apply_url

name

first_name

last_name

street

city

state

zip

location

message (allows you to send a custom message with each POST)

PivotCX uses id, phone, and email to identify the candidate. If id is not provided, Pivot will use the phone and/or email address as a unique identifier.

JSON

{
  "name": "Jane Doe",
  "phone": "+11112223333",
  "opt_in": true,
  "medium": "web",
  "source": "google",
  "campaign": "adwords",
  "street": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "zip": "94105",
  "job_title": "Stylist",
  "req_id": "123456",
  "cover": "I'm a great stylist -- Jane"
}

Form Multipart

opt_in=true
first_name=Batman
last_name=Tejas
street=1 N Pole Ave
email=mike+batman_tejas@pivotcx.io
city=Gotham City
state=TX
phone=+13177628911
id=man_who_dresses_like_a_bat
source=testing
keyword=batmans
campaign=superhero_recruiting
job_id=555
content=Man Who Dresses Like Bat
location=Hooptieville, TX USA
medium=test
message=This is a great opportunity to show my mad crimefighting skills.

Appendix III: Message Templates

Basic format

$variable_name(default text)

When a variable name follows the dollar sign character ($), it will be replaced with the variable’s value. You may supply default text that will be used if the variable is empty. For example, given firstname=Mike, title is empty, and teamname=PivotCX:

Hi $firstname(there) – You’ve applied for $title(a great job) at $teamname. Do you have time to talk now?

Will render to:

Hi Mike – You’ve applied for a great job at PivotCX. Do you have time to talk now?

Variables

Variable Description
$firstname The first name of the contact
$lastname The last name of the contact
$city The city where the contact lives
$state The state where the contact lives
$postalcode The postal code where the contact lives
$street The street address where the contact lives
$phone The primary phone number of the contact
$email The primary email of the contact
$teamname The public name of the team sending the messages
$title The job title that they applied for. Only available in send_application.

Appendix V: Delivery Message Example

{
    "contact": {
        "documentId": {"value": "unique_id_for_post", "schemeId": "Partner_name"},
        "uri": "https://www.jobboard.com/44k5jnw23kln",
        "person": {
            "id": {
                "value": "Candidate_id",
                "schemeId": "partner_name",
                "schemeAgencyId": "agency_name(optional)"
            },
            "name": {"formattedName": "John Smith"},
            "communication": {
                "email": [
                    {"address": "smith@mail.com", "useCode": "private", "preference": 1}
                ],
                "phone": [
                    {
                        "useCode": "private",
                        "preference": 1,
                        "formattedNumber": "+13175554444"
                    }
                ]
            }
        },
        "profiles": [
            {
                "profileId": {"value": "4w247145ghad", "schemeId": "YourATS"},
                "attachments": [
                    {
                        "id": {"value": "Resume"},
                        "content": {
                            "value": "UEsDBBQABgAIAAAAIQCidL (must be base64 encoded)",
                            "encoding": "base64",
                            "filename": "resume.pdf",
                            "mimeType": "application/pdf"
                        }
                    }
                ],
                "profileName": "Main profile",
                "languageCode": "en-US",
                "associatedPositionOpenings": [
                    {
                        "positionUri": "https://www.jobboard.com/44k5jnw23kln",
                        "positionTitle": "Hiring Manager",
                        "positionCompany": "Your Company",
                        "positionLocation": "US-IN-Fort Wayne",
                        "positionDescriptionHTML": "Job Description HTML (optional)",
                        "positionDescriptionText": "Job Description in plain text",
                        "positionDescriptionMarkdown": "Job Description in markdown",
                        "candidateAppliedIndicator": true
                    }
                ]
            }
        ]
    },
    "content": {
        "associatedPositionOpenings": [
            {
                "positionUri": "https://www.jobboard.com/44k5jnw23kln",
                "positionTitle": "Hiring Manager",
                "positionCompany": "Your Company",
                "positionLocation": "US-IN-Fort Wayne",
                "positionDescriptionHTML": "Job Description HTML (optional)",
                "positionDescriptionText": "Job Description in plain text (optional)",
                   "positionDescriptionMarkdown": "Job Description in Markdown",
                "callbackUrl": "https://www.jobboard.com/44k5jnw23kln/callback/",
                "candidateAppliedIndicator": true
            }
        ]
    },
    "conversation": {
        "uuid": "uuid4",
        "wrap_up": {
            "status": "open, closed, review, qualified, not qualified",
            "reason": "justification for status",
            "notes": "Notes from chat agent",
            "sent_to": ["mailto:test@email.com", "tel:+13171231234", "post_url"],
        },
        "transcript": [
            {
                "timestamp": "2021-01-06T14:57:32Z",
                "to": "+13171231234",
                "from": "+131744444144",
                "message_type": "event or chat",
                "message": "The message content"
            }
        ]
    }
}