Forms – Sarbacane – Documentation API

Add a webhook

Allows to create an webhook subscription

HTTP request

POST

https://api.sarbacane.com/v1/webhooks

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Body Parameters

Parameter	Description	Required
url	A valid https url (must be valid and https^)	yes
displayName	A display name of your webhook subscription	yes
kinds	An array with theses possibles following values : FORM_SUBMIT, HARD_BOUNCE, SOFT_BOUNCE, SUCCESSFUL, CAPTCHA, COMPLAINT, OPEN, HIT, UNSUBSCRIBE	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X POST "https://api.sarbacane.com/v1/webhooks"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"url":"https://help.sarbacane.com/suite/","displayName":"webhook description","kinds":["HARD_BOUNCE", "FORM_SUBMIT"]}'

HTTP Headers Authentication


curl -X POST "https://api.sarbacane.com/v1/webhooks"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"url":"https://help.sarbacane.com/suite/","displayName":"webhook description","kinds":["HARD_BOUNCE", "FORM_SUBMIT"]}'

HTTP success response code

HTTP/2 200

Get Webhooks

Allows to get all webhook subscriptions

HTTP request

GET

https://api.sarbacane.com/v1/webhooks

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body


[
 {
  "id":"webhookId",
  "accountId":"accountid",
  "displayName":"description",
  "url":"https://webhook.site/www-xxx-yyy-zzz",
  "kinds":["HARD_BOUNCE","SOFT_BOUNCE","SUCCESSFUL","CAPTCHA","COMPLAINT","OPEN","HIT","UNSUBSCRIBE"],
  "creationDate":"2025-04-23T13:54:26.938Z"
  },
  {...},
  {...}
]

Get Webhook

Allows to get a specific webhook

HTTP request

GET

https://api.sarbacane.com/v1/webhooks/{webhookId}

Header parameters

Parameter	Description	Required
accountID	Account ID	yes
apiKey	API key	yes

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
400	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks/{webhookId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication


curl -X GET "https://api.sarbacane.com/v1/webhooks/{webhookId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body


 {
  "id":"webhookId",
  "accountId":"accountid",
  "displayName":"description",
  "url":"https://webhook.site/www-xxx-yyy-zzz",
  "kinds":["HARD_BOUNCE","SOFT_BOUNCE","SUCCESSFUL","CAPTCHA","COMPLAINT","OPEN","HIT","UNSUBSCRIBE"],
  "creationDate":"2025-04-23T13:54:26.938Z"
  }

Webhooks’ responses

According to your different webhooks subscriptions, you may receive different JSON structures. Here bellow our JSON envelopes :

DELIVERED
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"date": "2025-05-05T09:26:15.557Z",
"type": "delivered",
"ID": "{webhookId}",
"State": "{campaignType}",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

OPEN
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8582,
"longitude": 2.3387,
"region": "EU",
"operatingSystem": "recipient OS",
"language": "recipient language",
"browser": "FIREFOX11 11.0",
"webmail": "webmail",
"date": "2025-05-05T09:29:59.499Z",
"type": "open",
"ID": "recipientId",
"State": "campaignType",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

CLICK
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8582,
"longitude": 2.3387,
"country": "FR",
"region": "EU",
"operatingSystem": "WINDOWS_10",
"language": "en-US",
"browser": "CHROME10 107.0.0.0",
"webmail": "Unknown",
"url": "https://www.url.com?utm_source=Sarbacane&utm_medium=email&utm_campaign=((CampaignName))",
"date": "2025-05-05T09:32:52.704Z",
"type": "click",
"ID": "recipientId",
"State": "NORMAL",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

UNSUBSCRIBE
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"latitude": 48.8709,
"longitude": 2.3561,
"country": "FR",
"region": "EU",
"city": "Paris",
"postcode": "75010",
"operatingSystem": "WINDOWS_10",
"language": "fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7",
"browser": "CHROME13 136.0.0.0",
"webmail": "Unknown",
"date": "2025-05-05T12:27:16.354Z",
"type": "unsubscribe",
"ID": "{contactId}",
"State": "NORMAL",
"Origin Kind": "LIST",
"Origin Caption": "origin",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": "MANUAL"
}

HARDBOUNCE
{
"email": "recipient@domain.com",
"campaignId": "{campaignId}",
"sendId": "{sendId}",
"subject": "Your subject",
"from": "from@domain.com",
"smtpDescription": "failed to find ip addr",
"category": "BAD_DOMAIN",
"returnCode": 505,
"date": "2025-05-05T12:34:50.631680671Z",
"type": "hard_bounce",
"ID": "recipientId",
"State": "NORMAL",
"Origin Kind": "MANUAL",
"Origin Caption": "",
"Email Correction": "",
"Phone Correction": "",
"Email": "recipient@domain.com",
"": ""
}

FORM SUBMIT
{
"fieldId-1": "data",
"fieldId-2": "data",
"EMAIL": "recipient@sarbacane.com",
"PHONE": "phone number",
"fieldId-3": "3",
"formId": "formId",
"formName": "form name",
"listId": "listId"
}

List yours forms

Allows you to retrieve all your forms

HTTP request

GET

GET https://api.sarbacane.com/v1/forms

Header parameters

Parameter	Description	Required
accountId	Accound Id	true
apiKey	API key	true

URL parameters

Parameter	Description	Required
offset	Start position	false
limit	Maximum number of returned elements - Max: 1 000	false

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication

curl -X GET "https://api.sarbacane.com/v1/forms"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication

curl -X GET "https://api.sarbacane.com/v1/forms"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

[
    {
        "id": "md1166aAQXOIdsDLcBzyQA",
        "name": "Name"
    }
]

Details of a form

Used to retrieve the details of a form

HTTP request

GET

GET https://api.sarbacane.com/v1/forms{formId}

Header parameters

Parameter	Description	Required
accountId	Accound Id	true
apiKey	API key	true

URL parameters

Parameter	Description	Required
formId	Id of the form	true

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication

curl -X GET "https://api.sarbacane.com/v1/forms/{formId}"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"

HTTP Headers Authentication

curl -X GET "https://api.sarbacane.com/v1/forms/{formId}"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
        "id": "md1166aAQXOIdsDLcBzyQA",
        "name": "Name"
    }

Change the name of a form

Lets you change the name of a form

HTTP request

PUT

PUT https://api.sarbacane.com/v1/forms{formId}/name

Header parameters

Parameter	Description	Required
accountId	Accound Id	true
apiKey	API key	true

Body Parameters

Parameter	Description	Required
name	New form name	true

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication

curl -X PUT "https://api.sarbacane.com/v1/forms/{formId}/name"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": ["Name 1"]}'

HTTP Headers Authentication

curl -X PUT "https://api.sarbacane.com/v1/forms/{formId}/name"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"name": ["Name 1"]}'

HTTP success response code

HTTP/2 200

List the teams of a form

Used to retrieve the teams associeted with a form

HTTP request

PUT

GET https://api.sarbacane.com/v1/forms{formId}/teams

Header parameters

Parameter	Description	Required
accountId	Accound Id	true
apiKey	API key	true

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support

HTTP Authentication

curl -X PUT "https://api.sarbacane.com/v1/forms/{formId}/teams"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"name": ["Name 1"]}'

HTTP Headers Authentication

curl -X GET "https://api.sarbacane.com/v1/forms/{formId}/teams"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"

HTTP success response code

HTTP/2 200

Response body

{
    "teams": [
      "9cee994b1836fe00018126b1",
      "9cee994b1836fe00018126b2"
    ]
}

Edit the teams of a form

Allows you to modify the teams associated with a form

HTTP request

PUT

PUT https://api.sarbacane.com/v1/forms{formId}/teams

Header parameters

Parameter	Description	Required
accountId	Accound Id	true
apiKey	API key	true

Body Parameters

Parameter	Description	Required
teams	Array containing team ids to link with the form	true

Errors

HTML Code	Error message	Description
401	NEED_ACCOUNT_ID	No account ID is specified in the request
401	NEED_API_KEY	No API key is specified in the request
401	API_KEY_UNAUTHORIZED	Invalid API key
404	SERVICE_*_UNREACHABLE	The requested service is unavailable
500	INTERNAL_SERVER_ERROR	Internal error, please contact support
500	FAILED TO ACQUIRE LOCK	Item already in use by another ressource

HTTP Authentication

curl -X PUT "https://api.sarbacane.com/v1/forms/{formId}/teams"
  -u "YOUR_ACCOUNTID:YOUR_API_KEY"
  -d '{"teams": ["9cee994b1836fe00018126b1", "9cee994b1836fe00018126b2"]}'

HTTP Headers Authentication

curl -X PUT "https://api.sarbacane.com/v1/forms/{formId}/teams"
  -H "accountId: YOUR_ACCOUNTID"
  -H "apiKey: YOUR_API_KEY"
  -d '{"teams": ["9cee994b1836fe00018126b1", "9cee994b1836fe00018126b2"]}'

HTTP success response code

HTTP/2 200