The Marketing API set is designed for communications with the Tiber Marketing partners. Use the API to send and receive information about lead generation and partner marketing support.


Available APIs: Create Lead  Add Lead Program 


TABLE OF CONTENTS

TABLE OF CONTENTS


Assumptions

This WIKI assumes that the reader has a strong understanding of Tiber Health and its marketing platforms. It is also assumed that the reader has a strong understanding and concepts of REST API patterns.


The user or developer communicating with Tiber Marketing API is required to get a key and secret from Tiber Health's support team to communicate with the REST API. 


Communicating

To communicate with the Tiber Marketing APIs, you need to obtain your API Cert (Key) and API Auth (Secret) from Tiber Health support (support@tiberhealth.com). Once you have obtained your API Cert and Auth keys, you will place them into the request's header. 


All requests to the Tiber Health Portal must be secure using the HTTPS protocol. 


The root URL for all the marketing API calls is: https://portal.tiberhealth.com/api/marketing/v1/


POST https://portal.tiberhealth.com/api/marketing/v1/{{ Method }}
Content-Type: application/json
Apicert: {{ API Cert }}
Apiauth: {{ API Auth }}


Create Lead

The Create Lead API allows marketing partners to send leads and add them to Tiber Health databases.


POST https://portal.tiberhealth.com/api/marketing/v1/leads


Request

The request is an array of the Create Lead Object.


Most of the fields are optional. Required fields will be identified in bold.


Request Base Object

[
    {{ Lead Object }},
    {{ Lead Object }}
]

Base Lead Object

There are two object types for creating leads. They both are extensions of the Base Lead Object.


{
  "context": string,           // See Notes Below
  "LeadKey": string            // Key to identify the student (See Notes)
  "firstName": string,         // REQUIRED
  "lastName": string,          // REQUIRED
  "birthDate": string,         // Any parsable format (preferred MM/DD/YYYY)
  "address1": string,           
  "address2": string,           
  "phoneNumber": string,        
  "phoneType": string,          // The phone type: mobile, cell, home, office
  "smsConsent": boolean,        // Offer consent for SMS/Text messages
  "emailAddress": string,       
  "ContactPreference": string,  // Preferred contact method: any, mobile, snail, mail
  "Country": string,            // Country or Country Abbr..
  "city": string,               
  "state": string,              
  "zipCode": string,            // Zip code, can include plus 4
  "declaredGender": string,     // Declared gender if provided
  "ethnicity": string,          
  "religiousAffiliation": string, 
  "prospectiveType": string,
  "collegeType": string,
  "capturedDate": Date/time,    // Any parsable format (preferred MM/DD/YYYY)
  "standardizedTest": string,   // Exam for Standardized Score (MCAT, GRE)
  "standardizedScore": string,  // Standardized Score
  "collegeUniversity": string,  // Last or current University
  "currentlyEnrolled": bool,    
  "graduationDate": Date | int, // Any parsable date format, can be just the year
  "gpa": decimal,               // Students current or latest GPA
  "scienceGpa": decimal,        // Student current or latest GPA in the Sciences
  "intendedDegree": string
}


Notes

  • context is a user-defined field to identify grouping to leads. Leads with the same context string will be group together and the first entry will become the parent and the other leads becoming children of the first lead and applied as such. If the context field is left out or is null, it will default to leadkey or {{Last Name}},{{First Name}}.
  • leadkey is an identifying field for the lead that can be passed to the lead API. Leads with the same leadkey will be linked in a parent-child relationship.
    • It is recommended that leadkey be a GUID or a hash that guarantees uniqueness across all leads in our database from all partners. 


Single School / Program Request

If the lead is only inquiring about one program and school, use the following fields to identify the school and program.


{
  ... {{ Lead Base Object }},
    "programSchool": string,    // School or Institution lead is interested
    "targetCampus": string,     // The campus, if needed, the lead is interested
    "programName": string,      // The name of the program the lead is interested
    "programCip": string.       // The Program CIP the lead is interested
}



Multiple School / Program Request

If the lead is interested in Multiple schools or programs, use the following array structure to create multiple lead records for the same lead. 


{
   ... {{ Lead Base Object }},
   "programs": [     // Array of school / program object
      {
           // if PostBId is provided, the program and institution fields
           // are overwritten with the information in the database
           "PostBId": int,     // Id from the Post Bacc database
 
          // Supply only if PostBId is not known or not used
          "Institution": string, 
          "Program Name": string
      },
      .....
   ]
}



The Multiple School/Program object will overwrite the Single School Object fields if they are both present.

Please only use one set of fields.


Result

When the leads have been processed the following result will be produced and returned from the API.

{
  "status": int,                    // Status Identifier
  "statusText": string,             // Status Text
  "results": [                      // Result from the Lead API
    {
      "context": string,            // The context passed or generated
      "key": string                 // Parent lead key for the context
    }
  ],
  "resultCount": int,               // Number of results
  "totalApiLoadTime": number,       // Total time the API took to process
  "totalProcessingTime": number,    // Total time the Lead generation took to process
  "message": string                 // Any messages generated by the process 
}


Add Lead Program

The Add Lead Program API allows marketing partners to add a new program to a lead already in the Tiber Health database.


PUT https://portal.tiberhealth.com/api/marketing/v1/leads


Request


Is a simplified Create Lead object that identifies the lead and the programs to add.


  {
    "LeadKey": string,
   "programs": [     // Array of school / program object
      {
           // if PostBId is provided, the program and institution fields
           // are overwritten with the information in the database
           "PostBId": int,     // Id from the Post Bacc database
 
          // Supply only if PostBId is not known or not used
          "Institution": string, 
          "Program Name": string
      },
   ]
}


Notes

  • leadkeyis an identifying field for the lead and is required to be a value of a previous lead that was imported.
    • If the leadkey is not found a 400 Bad Request is returned from the API.

Result

When the leads have been processed the following result will be produced and returned from the API.


{
  "status": int,                    // Status Identifier
  "statusText": string,             // Status Text
  "results": [                      // Result from the Lead API
    {
      "context": string,            // The context passed or generated
      "key": string                 // Parent lead key for the context
    }
  ],
  "resultCount": int,               // Number of results
  "totalApiLoadTime": number,       // Total time the API took to process
  "totalProcessingTime": number,    // Total time the Lead generation took to process
  "message": string                 // Any messages generated by the process 
}