Use the contacts API to log communication in NationBuilder.
Resources
Contact Resource
| Name | Description | Writable | Required | Example Value(s) |
| type_id | id of the contact type. For possible values use the Contact Types API. | Y | N | 5 |
| method | the method through which the contact was made. For possible values use the Contact Methods API. | Y | Y | door_knock |
| sender_id | id of the person who made the contact. | Y | Y | 63 |
| person_id | id of the person who receives the contact. | N | N | 342 |
| status | status of the contact. For possible values use the Contact Statuses API. | Y | N | not_interested |
| broadcaster_id | id of the broadcaster on whose behalf the sender made the contact | Y | N | 8123 |
| note | note about the content of the contact | Y | N | He did not support the cause |
| created_at | timestamp representing when the contact was created | Y | N | 2014-02-14T14:36:29-05:00 |
| capital_in_cents | virtual capital currency. This will default to 0 if not provided by the client. | Y | N | 10 |
| path_id | id of the path on which the contact is logged. | N | N | 5 |
| step_id | id of the path step on which the contact is logged. | N | N | 3 |
Index Endpoint
The index endpoint provides a paginated view of the contacts made to or received by a person.
GET /api/v1/contacts/
Required Parameters
-
person_id- the attribute of the person who is contacted, or -
author_id- the attribute of the person who made the contact.
Optional Parameters
-
limit- max number of results to show in one page of results (default 10, max 100). -
__nonce- generated pagination nonce. Do not modify. -
__token- generated pagination token. Do not modify. -
path_id- the resource attribute the contact was logged on. -
step_id- the resource attribute the contact was logged on. -
person_id- the attribute of the person who is contacted. -
author_id- the attribute of the person who made the contact.
Example
Assuming you have a person with id 7, make the request:
GET https://foobar.nationbuilder.com/api/v1/contacts?person_id=7
You will receive a response of status 200, with response body like this:
{
"next": "/api/v1/people/5/contacts?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m",
"prev": null,
"results": [
{
"type_id": 6,
"method": "email",
"author_id": 1,
"sender_id": 1,
"person_id": 7,
"recipient_id": 7,
"status": "left_message",
"broadcaster_id": null,
"note": null,
"created_at": "2014-02-14T14:36:29-05:00",
"capital_in_cents": 100,
"contact_id": 27,
"path_id": 1,
"step_id": 1
}
]
}
Create Endpoint
This endpoint creates a record of a contact with the provided data. It returns a full representation of the contact that was created. If the creation step fails, it returns an error.
POST /api/v1/people/:id/contacts
Parameters
-
contact- resource describing the contact you want to create
Example
Assuming you have a person with id 4123, make the request:
POST https://foobar.nationbuilder.com/api/v1/people/4123/contacts
With attached body content like this:
{
"contact": {
"sender_id": 1058,
"broadcaster_id": 10,
"status": "not_interested",
"method": "door_knock",
"type_id": 5,
"note": "He did not support the cause"
}
}
You will receive a response of status 200, with response body like this:
{
"contact": {
"type_id": null,
"method": "door_knock",
"author_id": 1058,
"sender_id": 1058,
"person_id": 4123,
"recipient_id": 4123,
"status": "not_interested",
"broadcaster_id": 10,
"note": "He did not support the cause",
"created_at": "2016-09-14T15:20:43-07:00",
"capital_in_cents": 0,
"contact_id": 29,
"path_id": null,
"step_id": null
}
}
Contact Types API
Use this API to list and define contact categories.
Index Endpoint
The index endpoint provides a paginated view of contact categories defined for a nation.
GET /api/v1/settings/contact_types
Parameters
-
limit- max number of results to show in one page of results (default 10, max 100). -
__nonce- generated pagination nonce. Do not modify. -
__token- generated pagination token. Do not modify.
Example
Make the request:
GET https://foobar.nationbuilder.com/api/v1/settings/contact_types
You will receive a response of status 200, with response body like this:
{
"next": "/api/v1/settings/contact_types?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m",
"prev": null,
"results": [
{
"id": 1,
"name": "Initial outreach"
},
{
"id": 2,
"name": "Question"
},
{
"id": 3,
"name": "Invite"
},
{
"id": 4,
"name": "Fundraising appeal"
},
{
"id": 5,
"name": "Volunteer recruitment"
},
{
"id": 6,
"name": "Thank you"
}
]
}
Create Endpoint
This endpoint creates a new contact category with the provided name. It returns a full representation of the contact category that was created. If the creation step fails, it returns an error.
POST /api/v1/settings/contact_types
Parameters
-
name- string you want to associate to the contact type
Example
Make the request:
POST https://foobar.nationbuilder.com/api/v1/settings/contact_types
With attached body content like this:
{
"contact_type": {
"name": "Pledge Drive 2013"
}
}
You will receive a response of status 200, with response body like this:
{
"contact_type": {
"id": 13,
"name": "Pledge Drive 2013"
}
}
Use the returned id to categorize a contact as this type.
Update Endpoint
This endpoint updates a contact type with the provided id and name. It returns a full representation of the updated contact type. If the update step fails, it returns an error.
PUT /api/v1/settings/contact_types/:id
Parameters
-
name- string you want to associate to the contact type
Example
Make this request (assuming you have a contact type with id 13):
PUT https://foobar.nationbuilder.com/api/v1/settings/contact_types/13
{
"contact_type": {
"name": "Pledge Drive Spring 2013"
}
}
You will receive a response of status 200, with response body like this:
{
"contact_type": {
"id": 13,
"name": "Pledge Drive Spring 2013"
}
}
Destroy Endpoint
This endpoint removes a contact type with the provided id. It takes no parameters and returns response code 204 on success.
DELETE /api/v1/settings/contact_types/:id
Contact Methods API
Use this API to lists the possible methods of contact.
Index Endpoint
The index endpoint provides a view of contact methods.
GET /api/v1/settings/contact_methods
Example
GET https://foobar.nationbuilder.com/api/v1/settings/contact_methods
{
"results": [
{
"name": "Delivery",
"api_name": "delivery"
},
{
"name": "Door knock",
"api_name": "door_knock"
},
{
"name": "Email",
"api_name": "email"
},
{
"name": "Email blast",
"api_name": "email_blast"
},
{
"name": "Face to face",
"api_name": "face_to_face"
},
{
"name": "Facebook",
"api_name": "facebook"
},
{
"name": "Meeting",
"api_name": "meeting"
},
{
"name": "Phone call",
"api_name": "phone_call"
},
{
"name": "Robocall",
"api_name": "robocall"
},
{
"name": "Snail mail",
"api_name": "snail_mail"
},
{
"name": "Text",
"api_name": "text"
},
{
"name": "Text blast",
"api_name": "text_blast"
},
{
"name": "Tweet",
"api_name": "tweet"
},
{
"name": "Video call",
"api_name": "video_call"
},
{
"name": "Webinar",
"api_name": "webinar"
},
{
"name": "Other",
"api_name": "other"
}
]
}
Contact Statuses API
Use this API to list the possible contact status categories.
Index Endpoint
The index endpoint provides a view of contact status categories.
GET /api/v1/settings/contact_statuses
Example
GET https://foobar.nationbuilder.com/api/v1/settings/contact_statuses
{
"results": [
{
"name": "Answered",
"api_name": "answered"
},
{
"name": "Bad info",
"api_name": "bad_info"
},
{
"name": "Left message",
"api_name": "left_message"
},
{
"name": "Meaningful interaction",
"api_name": "meaningful_interaction"
},
{
"name": "Not interested",
"api_name": "not_interested"
},
{
"name": "No answer",
"api_name": "no_answer"
},
{
"name": "Refused",
"api_name": "refused"
},
{
"name": "Send information",
"api_name": "send_information"
},
{
"name": "Other",
"api_name": "other"
}
]
}