fbpx

Contact API

You are here:
< All Topics
Table of Contents

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 truenot 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’

}