Contact API
Contact API
These API endpoints are for your SaaS to call on events that add value to your dashboard metrics.
All endpoints for Saturn Funnels are Post endpoints with JSON format and it is recommended that you use Https, though Http will work as well. This allows maximum security with the least amount of complexity.
Contacts
Contacts are all visitors to your WordPress website that fill out a form. All completed forms create a contact OR add to an existing contact.
Contacts are tracked on your website by unique a visitorId generated and stored on the browser.
Get Contact
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/get
{
api_key: string, // found in dashboard
// one of the following 3
email: string, // either email, visitorId or contact_id is required
visitorId: string, // either email, visitorId or contact_id is required
contact_id: string // unique contact identifier, either email, visitorId or contact _id is required
}
Results
JSON:
{
_id: string, // contact’s unique identifier aka contact_id
email: string,
created: Date,
name: string,
phone: string,
visitor_ids: [ string (mongoose.Schema.Types.ObjectId)], // multiple devices possible
tags: [string], // string array
unsubscribe_global: boolean,
active_sequences_ids: [string ], // string array
unsubscribed_sequences_ids: [string (mongoose.Schema.Types.ObjectId)],
unsubscribe_global: Boolean,
unsubscribe_broadcast: Boolean,
lead_score: number,
lead_level_updated: Date, // last update
lead_score_updated: Date,
trial_start: Date,
trial_end: Date,
aha_milestone: Boolean,
aha_date: Date, // if set
customer: Boolean,
customer_start: Date,
customer_end: Date, // if canceled
plan: String, // plan token, as defined in saturn funnels dashboard
custom: {
// Any custom fields added via a form or API, that are not above
}
}
Create/Update Contact
To add a new contact or update an existing contact.
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact
Along with the api_key, either the email or visitorId is required to create a contact.
Once a contact is created, you can also use the (_id) contact_id as an update selector..
Post as JSON:
{
api_key: string, // found in dashboard
// one of the following 3 …
// email is required to create a contact
email: string, // either email, visitorId or contact_id is required
visitorId: string, // either email, visitorId or contact_id is required
contact_id: string // contact _id, either email, visitorId or contact _id is required
// Fields that can be added or updated (all optional)
tags: [string], // string array
unsubscribe_global: boolean,
unsubscribe_global: Boolean,
unsubscribe_broadcast: Boolean,
lead_score: number,
lead_level_updated: Date, // last update
lead_score_updated: Date,
trial_start: Date,
trial_end: Date,
aha_milestone: Boolean,
aha_date: Date, // if set
customer: Boolean,
customer_start: Date,
customer_end: Date, // if canceled
plan: String, // plan token, as defined in saturn funnels dashboard
}
Warning: changing active_sequences_ids or unsubscribed_sequences_ids is directly a bad idea. Use these API endpoints instead.
Results
Returns the added or updated contact in JSON:
{
_id: string, // contact’s unique identifier aka contact_id
email: string,
created: Date,
name: string,
phone: string,
visitor_ids: [ string (mongoose.Schema.Types.ObjectId)], // multiple devices possible
tags: [string], // string array
unsubscribe_global: boolean,
active_sequences_ids: [string ], // string array
unsubscribed_sequences_ids: [string (mongoose.Schema.Types.ObjectId)],
unsubscribe_global: Boolean,
unsubscribe_broadcast: Boolean,
lead_score: number,
lead_level_updated: Date, // last update
lead_score_updated: Date,
trial_start: Date,
trial_end: Date,
aha_milestone: Boolean,
aha_date: Date, // if set
customer: Boolean,
customer_start: Date,
customer_end: Date, // if canceled
plan: String, // plan token, as defined in saturn funnels dashboard
custom: {
// Any custom fields added via a form or API, that are not above
}
}
Contact Delete
An endpoint to archive or delete a contact and all their information. If set permanent then the contact is permanently deleted as are all emails and identifiable events of the contact.
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/delete
{
api_key: string, // found in dashboard
// one of the following 3
email: string, // either email, visitorId or contact_id is required
visitorId: string, // either email, visitorId or contact_id is required
contact_id: string // unique contact identifier, either email, visitorId or contact _id is required
permanent: boolean // OPTIONAL, set true…not recoverable
}
Result:
{
status: ‘archived’ or ‘deleted’
}
Change Contact Lead Score
An endpoint to change a contact’s “Lead Score”. Either set it directly or increment/decrement by a specified amount.
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/change-score
{
api_key: string, // found in dashboard
// one of the following 3
email: string, // either email, visitorId or contact_id is required
visitorId: string, // either email, visitorId or contact_id is required
contact_id: string // unique contact identifier, either email, visitorId or contact _id is required
// One of the following 2
set_score: numer, // sert the contact’s score
add_to_score: number // a positive or negative number to change lead score by
}
Result:
{
contact_id: string, // contact _id
lead_score: number, // updated score
old_score: number
}
Add In-App Events to Contact
An endpoint to add In-App Events to a contact. Use the event_id from the User Interface: In-App Events > Define Event page.
These events are used for trials/onboarding/churn automations, and various reports in the dashboard.
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/event
{
api_key: string, // found in dashboard
// one of the following 2
contact_id: string, // unique contact identifier,
visitorId: string, // either contact_id or visitorId is required
event_id: string // required, from the dashboard
value: number, // default=1, optional
}
Result:
{
contact_id: string,
event_id: string,
status: ‘ok’
}
Add Trial/Onboarding Dates
An endpoint to add a trial/onboarding start and end dates to a contact. These are used for all trial/onboarding flows in your dashboard, automations triggers. Automation trigger:
- Trial Initiate
- Trial Expired
- You need to extend a trial end date via the API before the end date, otherwise, the “Trial Expired” may have been triggered. Why “may have”? Because this trigger has a days after expires parameter.
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/trial-onboard-dates
{
api_key: string, // found in dashboard
// one of the following 2
contact_id: string, // unique contact identifier,
visitorId: string, // either contact_id or visitorId is required
plan: string, // plan token defined in app
start: Date, // date string that will convert to a valid javascript date with new Date(start)
end: Date // date string that will convert to a valid javascript date with new Date(start)
}
Result:
{
contact_id: string, // contact _id
status: ‘updated’
}
Set Customer/Subscriber Status
An endpoint to turn ON or OFF a contact’s customer status. The start and end dates to a contact. These are used to see the complete trial or onboarding flow in your dashboard..
JSON Endpoint:
post: //api.saturnfunnels.com/api/app/contact/set-customer
{
api_key: string, // found in dashboard
// one of the following 2
contact_id: string, // unique contact identifier,
visitorId: string, // either contact_id or visitorId is required
customer: boolean, // true = is customer, include customer_start date,
//false=cancelled customer, include customer_end date
customer_start: Date, // date string that will convert to a valid javascript date with new Date(start)
customer_end: Date, // date string that will convert to a valid javascript date with new Date(start)
plan: string, // (optional) plan token defined in app
}
Result:
{
contact_id: string, // contact _id
status: ‘updated’
}
