Webhooks

Review Customer ID

Post review data back to your CRM
crm_id

Unique id that you include when requesting a review either through batch campaign or review request api

star_rating_overall

Overall star rating (0-5) of the review

review_content

Content of review

star_rating_value_for_money

Star rating for value for money (0-5) if available

star_rating_quality_of_service

Star rating for quality of service (0-5) if available

star_rating_customer_service

Star rating for customer service (0-5) if available

star_rating_company_trustworthiness

Star rating for company trustworthiness (0-5) if available

net_promoter_score

Net promoter score (0-10) if available

Review Customer ID payload
{
    "type": "review-customer-id",
    "data": {
        "crm_id": 100,
        "star_rating_overall": 5,
        "review_content": "Everything was great.",
        "star_rating_value_for_money": 4,
        "star_rating_quality_of_service": 5,
        "star_rating_customer_service": 5,
        "star_rating_company_trustworthiness": 3,
        "net_promoter_score": 9
    }
}

Referral Posting

Post referrals directly into your CRM. Requires Referral Module Subscription.
referral_first_name

First name of person who was referred

referral_last_name

Last name of person who was referred

referral_zipcode

Zip code of the referred

referral_phone

Phone number of referral

referring_customer_first_name

First name of referrer

referring_customer_last_name

Last name of referrer

referring_customer_phone

Phone number of referring customer

referring_customer_email

Email of referring customer

crm_id

Unique id that you include when requesting a referral either through batch campaign or referral request api

salesrep_first_name

First name of the sales rep user that generated the referral if from a sales rep's personal request in app. If the referral request was a personalized company request either through a batch campaign or via the referral request API where a a salesrep_first_name was included, then that salesrep_first_name would be included here. Otherwise this parameter will be left blank

salesrep_last_name

Last name of the sales rep user that generated the referral if from a sales rep's personal request in app. If the referral request was a personalized company request either through a batch campaign or via the referral request API where a a salesrep_last_name was included, then that salesrep_last_name would be included here. Otherwise this parameter will be left blank

salesrep_email

Email of the sales rep who worked with the customer

referral_source

Clarifies by which channel the referral was generated.....sales request, company request, reviewer, or Snoball

bc_referral_id

Unique ID from Snoball's system tied to that referral. This will be what is used in the Referral is qualified API and Referral became a sale API

promo_title

If you have a promo setup in Admin Controls then this will be the title of the promo

template_id

If you specified a template ID at the time of requesting a referral or review then this will be that specified template ID that was used

referral_payout

Amount offered for this referral

sale_payout

Amount offered for this referral should it turn into a sale

referral_message

The initial message the referral sends when they click Message or Text Me on the company interstitial page or rep profile page

trusted_form_cert

The trusted_form certificate generated when referral was captured

xxTrustedFormTokenxx

The trusted_form token generated when referral was captured

referral_type

This indicates whether the referral was shared by the customer or whether the referral submitted an inquiry through the customer's unique referral url.

Referral Posting payload
{
    "type": "referral-posting",
    "data": {
        "referral_first_name": "Alex",
        "referral_last_name": "Jobs",
        "referral_phone": "+15005550006",
        "referring_customer_first_name": "Lex",
        "referring_customer_last_name": "Smith",
        "referring_customer_phone": "+15005550007",
        "referring_customer_email": "[email protected]",
        "crm_id": 100,
        "salesrep_first_name": "Ben",
        "salesrep_last_name": "Gates",
        "salesrep_email": "[email protected]",
        "referral_source": "support request",
        "bc_referral_id": "98796159-8357-49eb-a55f",
        "promo_title": "Black Friday",
        "template_id": 1,
        "referral_payout": 10,
        "sale_payout": 20,
        "referral_message": "My friend referred me.",
        "trusted_form_cert": "https://cert.trustedform.com/823ba6cc357afa823ba6cc357afa",
        "xxTrustedFormTokenxx": "https://cert.trustedform.com/823ba6cc357afa823ba6cc357afa",
        "referral_type": "interstitial"
    }
}

Support Ticket

Post customer support related questions to your ticketing system.
ticket_title

Name of the ticket.

customer_first_name

First name of customer.

customer_last_name

Last name of customer.

customer_phone

Phone number of customer.

customer_email

Email of customer.

salesrep_first_name

First name of the sales rep who worked with the customer.

salesrep_last_name

Last name of the sales rep who worked with the customer.

salesrep_email

Email of the sales rep who worked with the customer.

conversation_array

Last 6 messages between the customer and messaging desk. Objects include sender, date, and message body.

crm_id

Unique id that you include when requesting a referral either through batch campaign or referral request api.

ticket_comments

Comments added by the messaging desk to provide additional context to the ticket.

Sales Ticket payload
{
    "type": "support-ticket",
    "data": {
        "ticket_title": "Help with XYZ123",
        "customer_first_name": "Steven",
        "customer_last_name": "Williams",
        "customer_phone": "+15005550006",
        "customer_email": "[email protected]",
        "salesrep_first_name": "John",
        "salesrep_last_name": "Brown",
        "salesrep_email": "[email protected]",
        "conversation_array": [
            {
                "sender": "customer",
                "date": "2023-12-20T09:15:00",
                "message_body": "Hi, I'm interested in your products. Can you provide more information?"
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T09:30:00",
                "message_body": "Certainly, John! Our products have various features. Which specific one are you interested in?"
            },
            {
                "sender": "customer",
                "date": "2023-12-20T10:00:00",
                "message_body": "I'm looking at XYZ123. How does it compare to ABC456?"
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T10:30:00",
                "message_body": "XYZ123 has advanced features compared to ABC456. Let me provide you with a detailed comparison."
            },
            {
                "sender": "customer",
                "date": "2023-12-20T11:00:00",
                "message_body": "Great! I'd appreciate that."
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T11:45:00",
                "message_body": "I've sent you an email with the detailed comparison. Please check your inbox."
            }
        ],
        "crm_id": "12345",
        "ticket_comments": "This customer needs help with XYZ123."
    }
}

Sales Ticket

Post customer support related questions to your ticketing system.
ticket_title

Name of the ticket.

customer_first_name

First name of customer.

customer_last_name

Last name of customer.

customer_phone

Phone number of customer.

customer_email

Email of customer.

salesrep_first_name

First name of the sales rep who worked with the customer.

salesrep_last_name

Last name of the sales rep who worked with the customer.

salesrep_email

Email of the sales rep who worked with the customer.

conversation_array

Last 6 messages between the customer and messaging desk. Objects include sender, date, and message body.

crm_id

Unique id that you include when requesting a referral either through batch campaign or referral request api.

ticket_comments

Comments added by the messaging desk to provide additional context to the ticket.

Referral Posting payload
{
    "type": "sales-ticket",
    "data": {
        "ticket_title": "Help with XYZ123",
        "customer_first_name": "Steven",
        "customer_last_name": "Williams",
        "customer_phone": "+15005550006",
        "customer_email": "[email protected]",
        "salesrep_first_name": "John",
        "salesrep_last_name": "Brown",
        "salesrep_email": "[email protected]",
        "conversation_array": [
            {
                "sender": "customer",
                "date": "2023-12-20T09:15:00",
                "message_body": "Hi, I'm interested in your products. Can you provide more information?"
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T09:30:00",
                "message_body": "Certainly, John! Our products have various features. Which specific one are you interested in?"
            },
            {
                "sender": "customer",
                "date": "2023-12-20T10:00:00",
                "message_body": "I'm looking at XYZ123. How does it compare to ABC456?"
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T10:30:00",
                "message_body": "XYZ123 has advanced features compared to ABC456. Let me provide you with a detailed comparison."
            },
            {
                "sender": "customer",
                "date": "2023-12-20T11:00:00",
                "message_body": "Great! I'd appreciate that."
            },
            {
                "sender": "messaging_rep",
                "date": "2023-12-20T11:45:00",
                "message_body": "I've sent you an email with the detailed comparison. Please check your inbox."
            }
        ],
        "crm_id": "12345",
        "ticket_comments": "This customer needs help with XYZ123."
    }
}

APIs

Authentication

The Snoball API uses API keys to authenticate requests. You can view and manage your API keys in the Dashboard, Admin Controls / API & Webhooks page. Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via bearer auth, use -H "Authorization: Bearer 3|9Y4SV4mqBXQLzfxWHtZ8wQz5okF6ncM9bi8DNlXF".
Authorization

Bearer 3|9Y4SV4mqBXQLzfxWHtZ8wQz5okF6ncM9bi8DNlXF

Review Request

Trigger a review request on behalf of the company via any of the three channels (text, email, phone). Personalization with the sales rep is optional. Phone outreach can not be personalized.
customer_first_name required

First name of customer

customer_last_name required

Last name of customer

customer_phone required

Phone number of customer

customer_zip required

Zip code of customer

customer_email required

Email of customer

outreach_method required

Indicate what outreach method you want Snoball to lead with. Text, Email or Phone If Email, we will ONLY attempt an email If Text, we will reach out through text first and then email if not contacted over text If Phone, we will reach through phone first and then email if not contacted over the phone

requesting_user_email required

Email for the referral desk user on account. Snoball will provide this

tcpa_consent required

Value must be 'yes'. By putting 'yes' into this field you are confirming that this contact has given you express written consent to reach out to them over SMS and Email and you are in compliance with TCPA laws

salesrep_first_name

First name of the sales rep who worked with the customer. Including this will personalize the outreach

salesrep_last_name

Last name of the sales rep who worked with the customer. Including this will personalize the outreach

salesrep_email

Email of sales rep

crm_id

Unique ID from your CRM. This will be included in the Review Customer ID webhook

template_id

For the text outreach method, specify which template you want to send out. You can find the template ID in your account under Templates -> Review Requests. If no template is specified then it will send the default system template.

Review Request body
{
    "customer_first_name": "Ty",
    "customer_last_name": "Bates",
    "customer_phone": "+15005550006",
    "customer_zip": "90011",
    "customer_email": "[email protected]",
    "outreach_method": "text",
    "salesrep_first_name": "Leonardo",
    "salesrep_last_name": "Brown",
    "salesrep_email": "[email protected]",
    "requesting_user_email": "[email protected]",
    "tcpa_consent": "yes",
    "crm_id": "1000",
    "template_id": 13
}

Review Request Error Codes

Code Description
200

Review requested successfully.

422
  • All validation errors
  • Invalid outreach method.
500

Internal server error

Referral Request

Trigger a referral request on behalf of the company. These referrals will be generated by customers sending in contacts or sharing the company profile page where their friends can request more information. The personalization of the sales rep is optional. Requires Referral Module Subscription.
customer_first_name required

First name of customer

customer_last_name required

Last name of customer

customer_phone required

Phone number of customer

requesting_user_email required

Email for the referral desk user on account. Snoball will provide this

customer_email required

Email of customer

tcpa_consent required

Value must be 'yes'. By putting 'yes' into this field you are confirming that this contact has given you express written consent to reach out to them over SMS and Email and you are in compliance with TCPA laws

customer_zipcode

Zip code of the customer

crm_id

Unique ID from your CRM. This will be included in the Referral Posting webhook

salesrep_first_name

First name of the sales rep who worked with the customer. Including this will personalize the initial outreach

salesrep_last_name

Last name of the sales rep who worked with the customer. Including this will personalize the initial outreach

salesrep_email

Email of the sales rep who worked with the customer. This will be included with the Referral Posting payload and can be used to route the referral directly to the sales rep if you'd like

template_id

Specify which template you want to send out. You can find the template ID in your account under Templates -> Referral Requests. If no template is specified then it will send the default system template

qualified_referral_payout

The payout amount, in cents, for a qualified referral. If left blank, the request will use the payout set in admin controls in your account

qualified_sale_payout

The payout amount, in cents, for a qualified sale. If left blank, the request will use the payout set in admin controls in your account

Referral Request body
{
    "customer_first_name": "Chad",
    "customer_last_name": "Gates",
    "customer_email": "[email protected]",
    "customer_phone": "+15005550006",
    "requesting_user_email": "[email protected]",
    "crm_id": 1000,
    "salesrep_first_name": "Leonardo",
    "salesrep_last_name": "Brown",
    "salesrep_email": "[email protected]",
    "template_id": 1,
    "tcpa_consent": "yes",
    "qualified_referral_payout": 1000,
    "qualified_sale_payout": 5000
}

Referral Request Error Codes

Code Description
201

Referral requested successfully.

422

All validation errors

  • Referral admin controls have to set the send referrals to parameter.
429

You have reached your referral request limit for the year.

500

Internal server error

503

A request to a 3rd party API failed

  • Unable to send referral request. Please try again later.
  • Unable to create contact. Please try again later.

Referral is Qualified

Tell Snoball when a referral is qualified. Updates funnel reporting and triggers payout (if you have a referral payout setup in admin controls). Requires Referral Module Subscription.
bc_referral_id required

Unique ID from Snoball's system tied to that referral. This was included in the Referral Posting Payload

is_qualified

Let us know if a referral is qualified or not. If you pass false that will tell us it IS NOT qualified. If you pass true or leave it empty we'll assume it IS qualified.

Referral is Qualified body
{
    "bc_referral_id": "98796890-74bd-40bd-865e",
    "is_qualified": true
}

Referral is Qualified Error Codes

Code Description
200

Referral updated successfully.

404

Referral does not exist.

409
  • This bc_referral_id has already been marked as a qualified referral and contact has been notified.
  • This bc_referral_id has already been marked as a qualified referral.
422

All validation errors

500

Internal server error

Referral Became a Sale

Tell Snoball when a referral turns into a sale. Updates funnel reporting and triggers payout (f you have a sale payout setup in admin controls). Requires Referral Module Subscription.
bc_referral_id required

Unique ID from Snoball's system tied to that referral. This was included in the Referral Posting Payload

is_qualified

Let us know if a referral turned into a sale or not. If you pass false that will tell us it DID NOT become a sale. If you pass true or leave it empty we'll assume it DID turn into a sale

Referral Became a Sale body
{
    "bc_referral_id": "98796890-74bd-40bd-865e",
    "is_qualified": false
}

Referral Became a Sale Error Codes

Code Description
200

Referral updated successfully.

404

Referral does not exist.

409
  • This bc_referral_id has already been marked as a qualified sale and contact has been notified.
  • This bc_referral_id has already been marked as a qualified sale.
422

All validation errors

500

Internal server error

Send Message

Send a sms message to the specified phone number.
customer_first_name required

First name of customer

customer_last_name required

Last name of customer

customer_phone required

Phone number of customer

requesting_user_email required

Email for the referral desk user on account. Snoball will provide this

customer_email required

Email of customer

tcpa_consent required

Value must be 'yes'. By putting 'yes' into this field you are confirming that this contact has given you express written consent to reach out to them over SMS and Email and you are in compliance with TCPA laws

template_id required

Specify which template you want to send out. You can find the template ID in your account under Templates -> Messages

customer_zipcode

Zip code of the customer

crm_id

Unique ID from your CRM. This will be included in the Referral Posting webhook

Send message body
{
    "customer_first_name": "Chad",
    "customer_last_name": "Gates",
    "customer_email": "[email protected]",
    "customer_phone": "+15005550006",
    "requesting_user_email": "[email protected]",
    "crm_id": 1000,
    "template_id": 1,
    "tcpa_consent": "yes"
}

Send Message Error Codes

Code Description
422

All validation errors

  • Referral admin controls have to set the send referrals to parameter.
500

Internal server error

503

A request to a 3rd party API failed

  • Unable to send sms message. Please try again later.
  • Unable to create contact. Please try again later.