{"error":"Malformed json."}

API

Required POST headers

All POST requests to the API must include the following header:

Content-Type: application/json

The POST payload must be JSON-formatted.

Error responses

If a request results in an error, the API will return a 400 http response code and return a JSON-formatted object like the following:

{
    errorCode: "SOME_ERROR_CODE",
    message: "A short description of the error."
}

The documentation for each method lists the different possible error codes.

---

Methods

• checkRegistrationCode
• contactSearch
• getTeamCoordinators
• createNewUser
• updateUser
• getUserData
• getCampaigns
• createFeedback
• createPreOutreachSurvey
• createPostOutreachReport
• deleteOutreachLocation
• updateNotificationPreferences
• unregisterFcmToken

checkRegistrationCode

checkRegistrationCode verifies whether a registration code is valid. If it is, it returns the related volunteer type and any other related information (like campaign ID).

Make a GET request to:

/api/checkRegistrationCode?code=[CODE]

GET parameters

Response payload

{
    success: true,
	volunteerType: 'volunteerDistributor' | 'ambassadorVolunteer',
	// for volunteerDistributor users:
	accountId: {string}, // representing one or more teams of volunteers
	isIndividualDistributor: {boolean},
	teamCoordinators: {
		name: {string},
		salesforceId: {string}
	}[]
}

Error codes ?

Example request

GET /api/checkRegistrationCode?code=correct-horse-battery-staple

contactSearch

contactSearch searches via email address or phone number for Salesforce Contact objects which are not associated with Firebase user accounts. If any unassociated Contact object has either the given email address or phone number, then that Contact's Id is returned.

Make a GET request to:

/api/contactSearch?email=[EMAIL_ADDRESS]&phone=[PHONE_NUMBER]

GET parameters

Response payload

{
    salesforceId: {string}
}

Error codes ?

Example request

GET /api/contactSearch?email=joe.blow@example.com&phone=5559092332

getTeamCoordinators

getTeamCoordinators returns the Salesforce Contact IDs and names for all users who are listed as volunteer team coordinators for a given Account.

Make a GET request to:

/api/getTeamCoordinators

GET parameters

Response payload

[
    {
        name: {string},
        salesforceId: {string}
    }, {
        name: {string},
        salesforceId: {string}
    },
    ...
]

Example request

GET /api/getTeamCoordinators?accountId=j9KeT4

createNewUser

createNewUser creates a new app user by associating a firebase uid with a Contact entry in Salesforce, creating a new Contact if needed.

Make a POST request to:

/api/createNewUser

POST request body payload parameters

Response payload

{
    contactId: {string} // the ID of the updated or newly created Contact object in Salesforce
}

Error codes ?

Example request

// URL:
POST /api/createNewUser

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "registrationCode": "correct-horse-battery-staple",
    "salesforceId": "JOF7EK0enoejMOE8",
    "isCoordinator": true,
    "trainingVideoRequiredForTeam": false
}

updateUser

updateUser updates fields on an existing user account.

Make a POST request to:

/api/updateUser

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/updateUser

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "coordinatorId": "KJD94JFR"
}

getUserData

getUserData provides a way for the TAT mobile app to get a user's data.

Make a POST request to:

/api/getUserData?parts=[LIST_OF_PARTS]

Required headers

See the section on required POST headers.

GET parameters

POST request body payload parameters

Response payload

The API returns a JSON object containing data on the user.

If basic is in the list of parts, the API will return basic info on the user.
The following properties will be included in the returned object:

{
    salesforceId: {string}, // the identifier of the object in Salesforce representing the user
    firstName: {string},
    lastName: {string},
    volunteerType: {string},
    accountId: {string},
    hasWatchedTrainingVideo: {boolean},
    trainingVideoLastWatchedDate: {string (ISO-8601 or YYYY-MM-DD)},
    street: {string},
    city: {string},
    state: {string},
    zip: {string},
    country: {string},
    isTeamCoordinator: {boolean},
    teamCoordinatorId: {string}, // ContactID of the salesforce object representing the user's team coordinator
    isOnVolunteerTeam: {boolean},
    trainingVideoRequiredForTeam: {boolean}
    notificationPreferences: {
		[ fcmToken: string ]: {
			language: {string},
			preEventSurveyReminderEnabled: {boolean},
			reportReminderEnabled: {boolean},
			upcomingEventsReminderEnabled: {boolean}
		}
    }
}

If unfinishedActivities is in the list of parts, the API will return a list of outreach activities (locations identified in pre-outreach form submissions) or events which the user has not completed a post-report for.
The following properties will be included in the returned object, if the user is a Volunteer Distributor:

{
    outreachLocations: [
        {
            id: {string}, // the identifier of the Salesforce object representing the outreach activity or event activity
            name: {string},
            type: {'cdlSchool' | 'truckingCompany' | 'truckStop' | 'event'},
            campaignId: {string},
            street: {string},
            city: {string},
            state: {string},
            zip: {string},
            country: {string},
            date: {string (ISO-8601 or YYYY-MM-DD)}, // planned date of outreach, or date of event
            contact: { // the person to be contacted at the defined location
                name: {string},
                title: {string},
                email: {string},
                phone: {string}
            }
        }, {
            ...
        }
    ]
}

Error codes ?

Example request

// URL:
POST /api/getUserData?parts=basic,unfinishedActivities

// Headers:
Content-Type: application/json

// Request body:
{ "firebaseIdToken": "abcd1234" }

getCampaigns

getCampaigns returns a list of campaigns associated with a user.

Make a POST request to:

/api/getCampaigns

POST request body payload parameters

Response payload

[
    {
        name: {string},
        salesforceId: {string},
		daysSinceCreated: {number}
    },
    ...
]

Example request

// URL:
POST /api/getCampaigns

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234"
}

createFeedback

createFeedback adds the data from a testimonial/feedback survey to Salesforce.

Make a POST request to:

/api/createFeedback

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/createFeedback

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "advice": "Show your passion for volunteering",
    "givesAnonPermission": true,
    "givesNamePermission": false
}

createPreOutreachSurvey

createPreOutreachSurvey adds the data from a pre-outreach survey to Salesforce. Creates multiple Outreach Location objects associated with the submitter's campaign.

Make a POST request to:

/api/createPreOutreachSurvey

POST request body payload parameters

Response payload

{
    success: true
}

Error codes ?

Example request

// URL:
POST /api/createPreOutreachSurvey

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
	"campaignId": "qrst4321",
	"isReadyToReceive": false,
	"locations": [
		{
			"name": "Love's",
			"street": "1234 Wowee St.",
			"city": "Blakefield",
			"state": "Oklahoma",
			"zip": "45454",
			"country": "United States",
			"hasContactedManager": false
		}
	]
}

createPostOutreachReport

createPostOutreachReport adds the data from a post-outreach report to Salesforce. Each report should be considered as a follow-up to a pre-outreach survey.

Make a POST request to:

/api/createPostOutreachReport

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/createPostOutreachReport

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "outreachLocationId": "IOJEHW8nEhehoh",
    "totalHours": 14,
    "completionDate": "2019-03-12",
    "accomplishments": ["willUseTatTraining"],
	"otherAccomplishments": ["Distributed some posters"],
    "contactFirstName": "Stan",
    "contactLastName": "Francisco",
    "contactTitle": "Asst manager",
    "contactEmail": "stanfran@example.com",
    "willFollowUp": false
}

deleteOutreachLocation

deleteOutreachLocation removes an Outreach Location, typically because the volunteers no longer intend to visit it.

Make a POST request to:

/api/deleteOutreachLocation

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/deleteOutreachLocation

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "outreachLocationId": "IOJEHW8nEhehoh"
}

updateNotificationPreferences

updateNotificationPreferences associates an FCM (Firebase Cloud Messaging) token with a user, so that the device associated with the token will receive the user's notifications. This also updates preferences associated with that FCM token.

Make a POST request to:

/api/updateNotificationPreferences

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/updateNotificationPreferences

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "fcmToken": "IOJEHW8nEhehoh",
    "language": "en",
    "reportReminderEnabled": false
}

unregisterFcmToken

unregisterFcmToken disassociates an FCM (Firebase Cloud Messaging) token from a user, so that any device associated with the token will no longer receive the user's notifications.

Make a POST request to:

/api/unregisterFcmToken

POST request body payload parameters

Response payload

{
    success: true
}

Example request

// URL:
POST /api/unregisterFcmToken

// Headers:
Content-Type: application/json

// Request body:
{
    "firebaseIdToken": "abcd1234",
    "fcmToken": "IOJEHW8nEhehoh"
}