Technical Documentation

Example Request

To save person data, a HTTP POST call that sends JSON data is required. At least the email is mandatory, we would suggest to also add an action.

A minimal example would be:


HTTP-POST: 
https://{Cambuildr-Url}/api/v1/people 

{ 
  "email" : "[email protected]", 
  "actions" : 
  [
   { 
    "name": "signup", // Action Verb: What happened?   
    "context": "Newsletter" // Context: What does the action refer? 
    "source": "Titel of Page" // Source: Where did the action happen? 
    "vendor": "Campaign Website", // System, optional 
   }
  ] 
}

The Cambuildr-URL can be found in the admin mask:

The complete URL for this example request would be https://demo.cambuildr.com/api/v1/people

Possible parameters

HTTP-POST: https://{Cambuildr-Url}/api/v1/people 
{ 
  "name" : "Markus", // first name, optional 
  "surname" : "Mustermann" // last name, optional 
  "email" : "[email protected]", // e-mail, mandatory 
  "campaign_id": 1234, // optional: associate the person with this campaign (by ID) 
  "actions" : 
  [
    { 
      "name": "signup", // Action Verb: What happened?   
      "context": "Newsletter" // Context: What does the action refer? 
      "source": "Titel of Page" // Source: Where did the action happen? 
      "vendor": "Campaign Website", // System, optional 
      "tags": ["Topic A", "Topic B"], // tags of the action, optional 
      "value": 10.00 // A value for this action. This value has to be numeric to be able to be used for selecting target audiences
      "custom_key": "custom_value" // arbitrary key-value pairs, that can be accessed in a triggered mail with the placeholder {{ var:action:custom_key }}
      "disclaimer_accepted": true, // if the signup disclaimer was accepted 
      "disclaimer_text": "I consent to the disclaimer..." // text of the disclaimer
    }
  ], 
  "tags":[ // optional
    { "screen_name":"tag-1" },
    { "screen_name":"tag-2" },
    { "id": 1234 }, // the tag id in CamBuildr
    { "id": 1234, "consent_accepted": true } // consentable tags need this parameter, see the note below
  ], 
  "gender": "m", // gender, optional (m or f) 
  "birthdate": "YYYY-MM-DD", //birthdate, optional 
  "phone": "+43 1 5323201", //phone number, optional 
  "address": { // address, optional 
    "street" : "Gölsdorfgasse 4/6", 
    "city" : "Wien", 
    "zip_code" : "1010", 
    "country_alpha2" : "AT" 
  }, 
  "custom_fields": // optional
  [
    { 
      "name": "Name of first custom field", 
      "value": "Value of first custom field" 
    },
    { 
      "name": "Name of second custom field", 
      "value": "Value of second custom field" 
    }
  ], 
  "social_connectors": [{ // optional
    "name": "custom", 
    "foreign_id": "12345", 
    "social_user_name": "External Name" 
  }] 
}

Notes

Custom fields

Please note, that the custom fields need to exist in the CamBuildr before they can be stored via the API. Otherwise an error '412 Precondition Failed' is returned.

Consentable tags

A consentable tag is only set when the tag object carries consent_accepted: true, next to either the screen_name or the id. Send the id as a number, not as a string. A consentable tag sent without the parameter is ignored, and consent_accepted: false is respected, so an unticked checkbox can be passed through as it is.

What happens next depends on the tag:

If the tag requires double opt-in, the consent is held back and a DOI email is sent. For a person who is not in the database yet, the whole signup waits in the quarantine zone: the response is a 201 without a person object, and nothing is stored until the recipient clicks the confirmation link. For an existing person, only the new consent waits.
If the tag does not require double opt-in, it is set immediately and the consent is logged with the tag's consent title and text. No email is sent.

Consents can only be given through the tags array. The actions[].tags field tags the action, not the person, and does not carry a consent. See Multi-Consent in CamBuildr for how consentable tags are configured.

Sending tags with authenticated user

Be aware, that, when sending tags (event with empty array), and are using this route with an authenticated user, all tags, that are not sent with the request, will be removed from the contact.

Campaign association

Sending an optional campaign_id associates the person with that campaign. When a new person is created, the campaign is also recorded on the person's creation action. Unknown or cross-tenant campaign IDs are silently ignored, and the person is still saved.

API: People/Actions