People API

Resources

Person Resource

active_customer_expires_at - the date at which to consider a customer no longer active
active_customer_started_at - the date from which a customer is considered active
author_id - the resource ID of the person who created this person in the nation
author - an abbreviated person resource representing the person who created this person’s record
auto_import_id - the ID given to a signup when a person is auto imported
availability - date and time this person is available (such as for volunteer shifts)
ballots - an array of ballot resources representing votes in elections
banned_at - the time and date this person was banned
billing_address - an address resource representing this person’s billing address
bio - the bio information that this person provided on their public profile via the “short bio” field
birthdate - this person's birth date
call_status_id - the ID of the call status associated with this person
call_status_name - the name of the call status associated with this person
capital_amount_in_cents - the balance of this person’s political or social capital, in cents
children_count - the number of people assigned to this person
church - the church that this person goes to
city_district - district field
city_sub_district - district field
civicrm_id - this person’s ID from CiviCRM
closed_invoices_amount_in_cents - the aggregate amount of all this person’s closed invoices in cents
closed_invoices_count - the number of closed invoices associated with this person
contact_status_id - ID of a contact status associated with this person. Possible values: 1: answered, 2: badinfo, 9: inaccessible, 3: leftmessage, 4: meaningfulinteraction, 6: notinterested, 7: noanswer, 8: refused, 5: sendinformation, 0: other
contact_status_name - name of a contact status associated with this person: Possible values: answered, badinfo, inaccessible, leftmessage, meaningfulinteraction, notinterested, noanswer, refused, sendinformation, other
could_vote_status - boolean indicating if this person could vote in an election or not, derived from their election-related IDs
county_district - district field
county_file_id - this person’s ID from a county voter file
created_at - timestamp representing when this person was created in the nation and also a writable attribute for new signups
demo - Asian, Black, Hispanic, White, Other, Unknown
do_not_call - this is a boolean flag that lets us know if this person is on a do not call list
do_not_contact - this is a boolean flag that lets us know if this person is on a do not contact list
donations_amount_in_cents - aggregate amount of all this person’s donations in cents
donations_amount_this_cycle_in_cents - the aggregate value of the donations this person made this cycle in cents
donations_count_this_cycle - the number of donations this person made this cycle
donations_count - the total number of donations made by this person
donations_pledged_amount_in_cents - the aggregate amount of the donations pledged by this person in cents
donations_raised_amount_in_cents - the aggregate amount of the donations raised by this person in cents, including their own donations
donations_raised_amount_this_cycle_in_cents - the aggregate value of all donations raised this cycle by this person, including their own
donations_raised_count_this_cycle - the number of donations raised this cycle by this person, including their own
donations_raised_count - the total number of donations raised
donations_to_raise_amount_in_cents - the goal amount of donations for this person to raise in cents
dw_id - this person’s ID from Catalist
email1_is_bad - boolean indicating if email1 for this person is bad
email1 - an email address for this person
email2_is_bad - boolean indicating if email2 for this person is bad
email2 - an email address for this person
email3_is_bad - boolean indicating if email3 for this person is bad
email3 - an email address for this person
email4_is_bad - boolean indicating if email4 for this person is bad
email4 - an email address for this person
email_opt_in - boolean representing whether this person has opted-in to email correspondence
email - when reading this field clients can expect the person's best email address to be returned. A person can have up to 4 email addresses: email1, email2, email3 and email4. The best email address is the one that is not marked as bad and is also marked as primary, that is, it is referenced by the primary_email_id field. When writing this field, its value will be assigned to one of email1, email2, email3 and email4 and it will be marked as primary. If all 4 email fields are already populated then the first one marked as bad will be overwritten. If none of the 4 email fields are marked as bad then the value of email will be dropped. In this case one of the 4 email fields and the primary_email_id have to be directly updated.
employer - the name of the company for which this person works
ethnicity - the ethnicity of this person as free text
external_id - a string representing an external identifier for this person
facebook_address - this person’s address based on their Facebook profile
facebook_profile_url - the URL of this person’s Facebook profile
facebook_updated_at - the date and time this person's Facebook info was last updated
facebook_username - this person's Facebook username
fax_number - the fax number associated with this person
federal_district - district field
federal_donotcall - boolean value indicating if this user is on the U.S. Federal Do Not Call list
fire_district - district field
first_donated_at - date and time of this person's first donation
first_fundraised_at - date and time that this person first raised donation
first_invoice_at - date and time of this person's first invoice
first_name - the person's first name and middle names
first_prospect_at - date and time that this user first became a prospect
first_recruited_at - date and time that this user was first recruited
first_supporter_at - date and time that this user became a supporter for the first time
first_volunteer_at - date and time that this person first volunteered
full_name - this person’s full name
has_facebook - a boolean representing whether this person has Facebook information
home_address - an address resource representing the home address
id - the NationBuilder ID of the person, specific to the authorized nation
import_id - the ID associated with this person when they were imported
inferred_party - the party the person is believed to be associated with
inferred_support_level - a possible support level
invoice_payments_amount_in_cents - total invoice payment amount (cents)
invoice_payments_referred_amount_in_cents - the aggregate amount of invoice payments made by recruits of this person (cents)
invoices_amount_in_cents - the aggregate amount of all of this person’s invoices (cents)
invoices_count - the number of invoices this person has
is_absentee_voter - a boolean field that indicates if the person votes absentee
is_active_voter - a boolean field that indicates if the person is actively voting
is_deceased - a boolean field that indicates if the person is alive or not
is_donor - a boolean field that indicates if the person has donated
is_early_voter - a boolean field that indicates if the person votes early
is_fundraiser - a boolean value that indicates if this person has previously fundraised
is_ignore_donation_limits - a boolean that indicates whether this person is not subject to donation limits associated with the nation
is_leaderboardable - a boolean that tells if this person is allowed to show up on the leaderboard
is_mobile_bad - a boolean reflecting whether this person’s cell number is invalid
is_permanent_absentee_voter - a boolean field that indicates if the person has registered as a permanent absentee voter
is_possible_duplicate - a boolean field that indicates if the NationBuilder matching algorithm thinks this person is a match to someone else in the nation
is_profile_private - a boolean that tells if this person’s profile is private
is_profile_searchable - a boolean that tells if this person’s profile is allowed to show up in search results
is_prospect - a boolean field that indicates if this person is a prospect
is_supporter - a boolean field that indicates if this person is a supporter
is_survey_question_private - a boolean field that indicates if this person’s survey responses are private
is_twitter_follower - whether the person is a Twitter follower of one of the nation’s broadcasters
is_volunteer - a boolean field that indicates whether the person has volunteered
judicial_district - a district field
labour_region - a district field
language - this person’s primary language
last_call_id - the id of the last contact to this person
last_contacted_at - the time and date of the last time this person was contacted
last_contacted_by - an abbreviated person resource representing the last user who contacted this person
last_donated_at - the time and date of this person’s last donation
last_fundraised_at - the time and date of the last time this person fundraised
last_invoice_at - the time and date of this person’s last invoice
last_name - this person's last name
last_rule_violation_at - the time and date of this person’s last rule violation
legal_name - the full (legal) name of this person
linkedin_id - this person’s ID from LinkedIn
locale - the ISO locale that the user has their administrative account set to (US, ES, FR etc.)
mailing_address - an address resource representing the mailing address
marital_status - the person’s marital status
media_market_name - the name of this person’s media market
meetup_address - an address resource based on this person’s profile in Meetup
meetup_id - this person's ID from Meetup
membership_expires_at - the time and date that this user’s membership expires
membership_level_name - the name of the level of this person’s membership
membership_started_at - the time and date that this user started a membership
middle_name - this person’s middle name
mobile_normalized - this person's cell phone number in normalized form
mobile_opt_in - a boolean representing whether the person has opted-in to mobile correspondence
mobile - this person's cell phone number
nbec_guid - this person’s ID from the NationBuilder Election Center
nbec_precinct_code - the unique identifier assigned to this person in the NationBuilder Election Center
ngp_id - this person’s ID from NGP
note_updated_at - the date and time the note attached to this person was updated
note - a note to attach to the person's profile
occupation - the type of work this person does
outstanding_invoices_amount_in_cents - the aggregate value of all this person’s outstanding invoices in cents
outstanding_invoices_count - the number of outstanding invoices this person has
overdue_invoices_count - the number of overdue invoices this person has
page_slug - the page this person first signed up from
parent_id - the NationBuilder ID of this person’s point person
parent - an abbreviated person resource representing this person’s point person
party_member - a boolean that tells if this person is a member of a political party
party - a one-letter code representing provincial parties for nations
pf_strat_id - a person’s historical ID from PoliticalForce
phone_normalized - this person's home phone number in normalized form
phone_time - the time that has been selected as the best time to call this person
phone - this person's home phone number
precinct_code - the code of the precinct that this person lives in
precinct_id - the ID of the precinct associated with this person
precinct_name - the name of the precinct that this person votes in
prefix - the name prefix of this person, i.e. Mr., Mrs.
previous_party - the party this person had selected before their current party selection
primary_email_id - the id of the primary email address associated with this person, one of: 1, 2, 3 or 4. This id corresponds to the 4 email addresses a person can have: email1, email2, email3 and email4.
priority_level_changed_at - the date and time that this person’s priority level changed
priority_level - the priority level associated with this person
profile_content_html - the profile content for this person’s public profile in HTML
profile_content - the content for this person’s public profile
profile_headline - the headline for this person’s public profile
received_capital_amount_in_cents - the aggregate amount of political capital ever received by this person
profile_image_url_ssl - the URL for this person's thumbnail image (read only)
recruiter_id - the ID of the person who recruited this person
recruiter - an abbreviated person resource representing the person who recruited this person
recruits_count - the number of people that were recruited by this person
registered_address - an address resource representing the registered address
registered_at - the date this person registered to become a voter
religion - this person’s religion
rnc_id - this person’s ID from the RNC
rnc_regid - this person’s registration ID from the RNC
rule_violations_count - the number of times this person has violated one of the nation’s rules
salesforce_id - this person’s ID from Salesforce
school_district - a district field
school_sub_district - a district field
sex - this person's gender (M, F or O)
signup_type - '0' for person, '1' for organization
spent_capital_amount_in_cents - the aggregate amount of capital ever spent by this person (in cents)
state_file_id - this person’s ID from a state voter file
state_lower_district - a district field
state_upper_district - a district field
submitted_address - the address this person submitted
subnations - an array of subnations that this person belongs to
suffix - the suffix this person uses w/their name, i.e. Jr., Sr. or III
support_level_changed_at - the time and date that this person’s support level changed
support_level - the level of support this person has for your nation, expressed as a number between 1 and 5, 1 being Strong support, 5 meaning strong opposition, and 3 meaning undecided.
support_probability_score - the likelihood that this person will support you at election time
supranational_district - district field
tags - the tags assigned to this person, as an array of strings
turnout_probability_score - the probability that this person will turn out to vote
twitter_address - this person’s location based on their Twitter profile
twitter_description - the description that this person provided in their Twitter profile
twitter_followers_count - the number of followers this person has on Twitter
twitter_friends_count - the number of friends this person has on Twitter
twitter_id - this person’s ID from Twitter
twitter_location - an address resource representing this person’s address based on Twitter’s location data
twitter_login - this person’s Twitter login name
twitter_name - this person’s Twitter handle, e.g. FoobarSoftwares
twitter_updated_at - the last time this person’s Twitter record was updated
twitter_website - the URL of the website that this person included in their Twitter profile
unsubscribed_at - the date/time that this person unsubscribed from emails
updated_at - the timestamp representing when this person was last updated
user_submitted_address - an address resource representing the address this person submitted
username - this person’s NationBuilder username
van_id - this person’s ID from VAN
village_district - a district field
voter_updated_at - the last time voter data was gathered for this person
warnings_count - the number of warnings this person has received
website - the URL of this person’s website
work_address - an address resource representing this person’s work address
work_phone_number - a work phone number for this person

Abbreviated Person Resource

birthdate - this person's birth date
city_district - district field
civicrm_id - this person’s ID from CiviCRM
county_district - district field
county_file_id - this person’s ID from a county voter file
created_at - timestamp representing when this person was created in the nation
do_not_call - this is a boolean flag that lets us know if this person is on a do not call list
do_not_contact - this is a boolean flag that lets us know if this person is on a do not contact list
dw_id - this person’s ID from Catalist
email_opt_in - boolean representing whether this person has opted-in to email correspondence
email - the person's email address if reading or writing a single address
employer - the name of the company for which this person works
external_id - a string representing an external identifier for this person
federal_district - district field
fire_district - district field
first_name - the person's first name and middle names
has_facebook - a boolean representing whether this person has Facebook information
id - the NationBuilder ID of the person, specific to the authorized nation
is_twitter_follower - whether the person is a Twitter follower of one of the nation’s broadcasters
is_volunteer - a boolean field that indicates whether the person has volunteered
judicial_district - district field
labour_region - district field
last_name - this person's last name
linkedin_id - this person’s ID from LinkedIn
mobile_opt_in - a boolean representing whether the person has opted-in to mobile correspondence
mobile - this person's cell phone number
nbec_guid - this person’s ID from the NationBuilder Election Center
ngp_id - this person’s ID from NGP
note - a note to attach to the person's profile
occupation - the type of work this person does
party - a one-letter code representing provincial parties for nations
pf_strat_id - a person’s historical ID from PoliticalForce
phone - this person's home phone number
precinct_id - the ID of the precinct associated with this person
primary_address - an address resource representing the primary address
recruiter_id - the ID of the person who recruited this person
rnc_id - this person’s ID from the RNC
rnc_regid - this person’s registration ID from the RNC
salesforce_id - this person’s ID from Salesforce
school_district - district field
school_sub_district - district field
sex - this person's gender (M, F or O)
state_file_id - this person’s ID from a state voter file
state_lower_district - district field
state_upper_district - district field
support_level - the level of support this person has for your nation, expressed as a number between 1 and 5, 1 being Strong support, 5 meaning strong opposition, and 3 meaning undecided.
supranational_district - district field
tags - the tags assigned to this person, as an array of strings
twitter_id - this person’s ID from Twitter
twitter_name - this person’s Twitter handle, e.g. FoobarSoftwares
updated_at - the timestamp representing when this person was last updated
van_id - this person’s ID from VAN
village_district - district field

Address Resource

"primary_address" is not a writable field. Instead, address data should be written to "work_address", "billing_address", "registered_address", or "home_address" fields. The profile will take the first address type field as the "primary_address". The primary address can also be updated to a different address type in the control panel under People > Edit > "Primary address".

address1 - first address line
address2 - second address line
address3 - third address line
city - city
state - state
zip - zip code
country_code - country code (using ISO-3166-1 alpha-2)
lat - latitude (using WGS-84)
lng - longitude (using WGS-84)

Ballot Resource

cast_at - when the ballot was cast,
country_code - country code (using ISO-3166-1 alpha-2) for the country the ballot was cast (required),
election_at - when the election was held (required),
election_period - the type of election (General, Primary, Presidential Primary, or Special, not case sensitive, not required for international elections),
party - party for primary elections (http://nationbuilder.com/politicalpartycodes),
state - which state the election was held in (required for US elections),
vote_method - how the ballot was cast (required)

Count Endpoint

The count endpoint provides a total count of all the people in the nation.

GET /api/v1/people/count

Example

GET https://foobar.nationbuilder.com/api/v1/people/count

{
  "people_count": 90013
}

Index Endpoint

The index endpoint provides a paginated view of the people in a nation. Each person's data is abbreviated for the Index view. To get a full representation use the Show endpoint

GET /api/v1/people

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

GET https://foobar.nationbuilder.com/api/v1/people

{
  "next": "/api/v1/people?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m",
  "prev": null,
  "results": [
    {
      "birthdate": "1973-04-04",
      "city_district": null,
      "civicrm_id": 7,
      "county_district": "11",
      "county_file_id": "97076395",
      "created_at": "2014-02-02T11:51:23-05:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": null,
      "email": "[email protected]",
      "email_opt_in": true,
      "employer": "Sun Film Foundation",
      "external_id": "781986",
      "federal_district": "0",
      "fire_district": null,
      "first_name": "Fernando",
      "has_facebook": false,
      "id": 453,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": null,
      "labour_region": null,
      "last_name": "Esteban",
      "linkedin_id": null,
      "mobile": "5738882938",
      "mobile_opt_in": true,
      "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
      "ngp_id": null,
      "note": "Has 3 kids. Ask about the baby on the way",
      "occupation": "Community Organizer",
      "party": "P",
      "pf_strat_id": 91207702,
      "phone": "2156726335",
      "precinct_id": null,
      "primary_address": {
        "address1": "448 S Hill St",
        "address2": "Suite 200",
        "address3": null,
        "city": "Los Angeles",
        "state": "CA",
        "country_code": "US",
        "zip": "90013",
        "lat": 34.0502,
        "lng": -117.2478
      },
      "profile_image_url_ssl": null,
      "recruiter_id": null,
      "rnc_id": 2653431,
      "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": null,
      "school_district": "Chicago Public Schools",
      "school_sub_district": null,
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "100000012",
      "state_lower_district": "024",
      "state_upper_district": "1",
      "support_level": 1,
      "supranational_district": "Eastern Euro Region",
      "tags": [],
      "twitter_id": "63403772",
      "twitter_name": "AngryPig",
      "updated_at": "2014-02-02T11:51:23-05:00",
      "van_id": "2",
      "village_district": null
    },
    {
      "birthdate": "1943-03-06",
      "city_district": null,
      "civicrm_id": 9,
      "county_district": "12",
      "county_file_id": "27376395",
      "created_at": "2014-02-02T11:51:23-05:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": null,
      "email": "[email protected]",
      "email_opt_in": true,
      "employer": "Moon Film Foundation",
      "external_id": "381986",
      "federal_district": "0",
      "fire_district": null,
      "first_name": "Alice",
      "has_facebook": false,
      "id": 672,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": null,
      "labour_region": null,
      "last_name": "Cooper",
      "linkedin_id": null,
      "mobile": "1242882938",
      "mobile_opt_in": true,
      "nbec_guid": "000088dc-00f0-11e2-b349-27c4eb6c1979",
      "ngp_id": null,
      "note": "Still single.",
      "occupation": "Community Organizer",
      "party": "P",
      "pf_strat_id": 21207702,
      "phone": "9216726335",
      "precinct_id": null,
      "primary_address": {
          "address1": "High St",
          "address2": "Apt 2312",
          "address3": "Suite 5A",
          "city": "Dallas",
          "state": "TX",
          "country_code": "US",
          "zip": "23891",
          "lat": 34.0502,
          "lng": -117.2478
      },
      "profile_image_url_ssl": null,
      "recruiter_id": null,
      "rnc_id": 2652231,
      "rnc_regid": "002D2ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": null,
      "school_district": "Dallas Public Schools",
      "school_sub_district": null,
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "100000013",
      "state_lower_district": "024",
      "state_upper_district": "1",
      "support_level": 1,
      "supranational_district": "Scotland Euro Region",
      "tags": [],
      "twitter_id": "13203772",
      "twitter_name": "AngryBird",
      "updated_at": "2014-02-02T11:51:23-05:00",
      "van_id": "2",
      "village_district": null
    }
  ]
}

Show Endpoint

The Show endpoint returns a full representation of the person with the provided id. It takes no parameters.

GET /api/v1/people/:id

Parameters

id_type - type of id to use, set to 'external' to show the person based on their external id

Example

Make a request like this:

GET /api/v1/people/672

or this:

GET /api/v1/people/8491?id_type=external

You will receive a response of status 200, with response body like this:

{
  "person": {
    "birthdate": "1973-04-04",
    "city_district": "city_district_1",
    "civicrm_id": 123489,
    "county_district": "county_district_1",
    "county_file_id": "mycountyfileid",
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": 987,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": "Texas Instruments",
    "external_id": "8491",
    "federal_district": "federal_district_1",
    "fire_district": "fire_district_1",
    "first_name": "Bob",
    "has_facebook": true,
    "id": 672,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": "judicial_district_1",
    "labour_region": "labour_region_1",
    "last_name": "Smith",
    "linkedin_id": "linkedinid",
    "mobile": "5738882938",
    "mobile_opt_in": true,
    "nbec_guid": "c4545",
    "ngp_id": "myngpid",
    "note": "Has 3 kids. Ask about the baby on the way",
    "occupation": "Programmer",
    "party": "P",
    "pf_strat_id": 876,
    "phone": "2156726335",
    "precinct_id": 21,
    "primary_address": null,
     "profile_image_url_ssl": null,
    "recruiter_id": 3421,
    "rnc_id": 1234567,
    "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
    "salesforce_id": "salesforceid",
    "school_district": "school_district_1",
    "school_sub_district": "school_sub_district_1",
    "sex": "F",
    "signup_type": 0,
    "state_file_id": "a12345z",
    "state_lower_district": "state_lower_district_1",
    "state_upper_district": "state_upper_district_1",
    "support_level": 1,
    "supranational_district": "region_abc",
    "tags": [],
    "twitter_id": "765",
    "twitter_name": "AngryPig",
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": "d6767",
    "village_district": "village_district_1",
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": "anytime",
    "banned_at": null,
    "billing_address": null,
    "bio": "Specialist in management and business growth.",
    "call_status_id": 5,
    "call_status_name": "no-answer",
    "capital_amount_in_cents": 0,
    "children_count": 2,
    "church": "Liberty Church",
    "city_sub_district": "DOWNTOWN LOS ANGELES",
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": 3,
    "contact_status_name": "Answered",
    "could_vote_status": 1,
    "demo": "W",
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": "http://www.facebook.com/profile.php?id=124071",
    "facebook_updated_at": "2014-02-25T11:22:12-04:00",
    "facebook_username": "alice",
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": "2013-02-02T11:51:23-05:00",
    "first_fundraised_at": "2013-04-02T11:51:23-05:00",
    "first_invoice_at": "2013-01-02T11:51:23-05:00",
    "first_prospect_at": "2013-11-02T11:51:23-05:00",
    "first_recruited_at": "2013-05-02T11:51:23-05:00",
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": "2013-05-02T11:51:23-05:00",
    "full_name": "Bob Smith",
    "home_address": null,
    "import_id": null,
    "inferred_party": "H",
    "inferred_support_level": 1,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": "EN",
    "last_call_id": 2378,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": "2014-02-02T11:51:23-05:00",
    "last_fundraised_at": "2014-01-01T11:51:23-05:00",
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": "en",
    "mailing_address": null,
    "marital_status": "S",
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": "T.",
    "mobile_normalized": null,
    "nbec_precinct_code": null,
    "note_updated_at": "2014-01-01T11:51:23-05:00",
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": false,
    "phone_normalized": null,
    "phone_time": "daytime",
    "precinct_code": "9876",
    "precinct_name": "9876",
    "prefix": null,
    "previous_party": "U",
    "primary_email_id": 1,
    "priority_level": 4,
    "priority_level_changed_at": null,
    "profile_content": "I support Abraham Lincoln for President.",
    "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
    "profile_headline": "Abe is back!",
    "received_capital_amount_in_cents": 0,
    "recruiter": {
      "birthdate": "1962-03-03",
      "city_district": null,
      "civicrm_id": 9,
      "county_district": "11",
      "county_file_id": "97076395",
      "created_at": "2014-02-02T11:51:23-05:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": null,
      "email": null,
      "email_opt_in": true,
      "employer": "Sun Film Foundation",
      "external_id": "781986",
      "federal_district": "0",
      "fire_district": null,
      "first_name": "Mina",
      "has_facebook": false,
      "id": 3421,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": null,
      "labour_region": null,
      "last_name": "Abbott",
      "linkedin_id": null,
      "mobile": "5738882938",
      "mobile_opt_in": true,
      "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
      "ngp_id": null,
      "note": "Has 3 kids. Ask about the baby on the way",
      "occupation": "Community Organizer",
      "party": "P",
      "pf_strat_id": 91207702,
      "phone": "2156726335",
      "precinct_id": null,
      "primary_address": null,
      "profile_image_url_ssl": null,
      "recruiter_id": null,
      "rnc_id": 2653431,
      "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": null,
      "school_district": "Chicago Public Schools",
      "school_sub_district": null,
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "100000012",
      "state_lower_district": "024",
      "state_upper_district": "1",
      "support_level": 1,
      "supranational_district": "Eastern Euro Region",
      "tags": [],
      "twitter_id": "63403772",
      "twitter_name": "AngryPig",
      "updated_at": "2014-02-02T11:51:23-05:00",
      "van_id": "2",
      "village_district": null
    },
    "recruits_count": 0,
    "registered_address": null,
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": "123 Main St Portland, ME 04101",
    "subnations": ["abeforprez", "operalovers"],
    "suffix": null,
    "support_level_changed_at": "2014-02-02T11:51:23-05:00",
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": "Animal lover.",
    "twitter_followers_count": 564,
    "twitter_friends_count": 32,
    "twitter_location": "Dallas, TX",
    "twitter_login": "trinity",
    "twitter_updated_at": "2014-01-01T11:51:23-05:00",
    "twitter_website": "http://mytwittersite.com",
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": {
    "id": 21,
    "code": "9876",
    "name": "9876"
  }
}

Match Endpoint

Use the match endpoint to find people that have certain attributes. A single person must match the given criteria for this endpoint to return success.

GET /api/v1/people/match

Parameters

Parameters act as matching criteria.

email - email address
first_name - first name
last_name - last name
phone - phone number
mobile - mobile number

Example

Make the request:

GET https://foobar.nationbuilder.com/api/v1/people/[email protected]

You will receive a response with a body like this if the person exists:

{
    "person": {
        "birthdate": "1973-04-04",
        "city_district": "city_district_1",
        "civicrm_id": 123489,
        "county_district": "county_district_1",
        "county_file_id": "mycountyfileid",
        "created_at": "2014-02-02T11:51:23-05:00",
        "do_not_call": false,
        "do_not_contact": false,
        "dw_id": 987,
        "email": "[email protected]",
        "email_opt_in": true,
        "employer": "Texas Instruments",
        "external_id": "external",
        "federal_district": "federal_district_1",
        "fire_district": "fire_district_1",
        "first_name": "Bob",
        "has_facebook": true,
        "id": 98,
        "is_twitter_follower": false,
        "is_volunteer": false,
        "judicial_district": "judicial_district_1",
        "labour_region": "labour_region_1",
        "last_name": "Smith",
        "linkedin_id": "linkedinid",
        "mobile": "5738882938",
        "mobile_opt_in": true,
        "nbec_guid": "c4545",
        "ngp_id": "myngpid",
        "note": "Has 3 kids. Ask about the baby on the way",
        "occupation": "Programmer",
        "party": "P",
        "pf_strat_id": 876,
        "phone": "2156726335",
        "precinct_id": 77,
        "primary_address": null,
       "profile_image_url_ssl": null,
        "recruiter_id": 233,
        "rnc_id": 1234567,
        "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
        "salesforce_id": "salesforceid",
        "school_district": "school_district_1",
        "school_sub_district": "school_sub_district_1",
        "sex": "F",
        "signup_type": 0,
        "state_file_id": "a12345z",
        "state_lower_district": "state_lower_district_1",
        "state_upper_district": "state_upper_district_1",
        "support_level": 1,
        "supranational_district": "region_abc",
        "tags": [],
        "twitter_id": "765",
        "twitter_name": "AngryPig",
        "updated_at": "2014-02-02T11:51:23-05:00",
        "van_id": "d6767",
        "village_district": "village_district_1",
        "active_customer_expires_at": null,
        "active_customer_started_at": null,
        "author": null,
        "author_id": null,
        "auto_import_id": null,
        "availability": "anytime",
        "banned_at": null,
        "billing_address": null,
        "bio": "Specialist in management and business growth.",
        "call_status_id": 5,
        "call_status_name": "no-answer",
        "capital_amount_in_cents": 0,
        "children_count": 2,
        "church": "Liberty Church",
        "city_sub_district": "DOWNTOWN LOS ANGELES",
        "closed_invoices_amount_in_cents": null,
        "closed_invoices_count": null,
        "contact_status_id": 3,
        "contact_status_name": "Answered",
        "could_vote_status": 1,
        "demo": "W",
        "donations_amount_in_cents": 0,
        "donations_amount_this_cycle_in_cents": 0,
        "donations_count": 0,
        "donations_count_this_cycle": 0,
        "donations_pledged_amount_in_cents": 0,
        "donations_raised_amount_in_cents": 0,
        "donations_raised_amount_this_cycle_in_cents": 0,
        "donations_raised_count": 0,
        "donations_raised_count_this_cycle": 0,
        "donations_to_raise_amount_in_cents": 0,
        "email1": "[email protected]",
        "email1_is_bad": false,
        "email2": null,
        "email2_is_bad": false,
        "email3": null,
        "email3_is_bad": false,
        "email4": null,
        "email4_is_bad": false,
        "ethnicity": null,
        "facebook_address": null,
        "facebook_profile_url": "http://www.facebook.com/profile.php?id=124071",
        "facebook_updated_at": "2014-02-25T11:22:12-04:00",
        "facebook_username": "alice",
        "fax_number": null,
        "federal_donotcall": false,
        "first_donated_at": "2013-02-02T11:51:23-05:00",
        "first_fundraised_at": "2013-04-02T11:51:23-05:00",
        "first_invoice_at": "2013-01-02T11:51:23-05:00",
        "first_prospect_at": "2013-11-02T11:51:23-05:00",
        "first_recruited_at": "2013-05-02T11:51:23-05:00",
        "first_supporter_at": "2014-02-02T11:51:23-05:00",
        "first_volunteer_at": "2013-05-02T11:51:23-05:00",
        "full_name": "Bob Smith",
        "home_address": null,
        "import_id": null,
        "inferred_party": "H",
        "inferred_support_level": 1,
        "invoice_payments_amount_in_cents": 0,
        "invoice_payments_referred_amount_in_cents": 0,
        "invoices_amount_in_cents": null,
        "invoices_count": null,
        "is_deceased": false,
        "is_donor": false,
        "is_fundraiser": false,
        "is_ignore_donation_limits": false,
        "is_leaderboardable": true,
        "is_mobile_bad": false,
        "is_possible_duplicate": false,
        "is_profile_private": false,
        "is_profile_searchable": true,
        "is_prospect": false,
        "is_supporter": true,
        "is_survey_question_private": false,
        "language": "EN",
        "last_call_id": 2378,
        "last_contacted_at": null,
        "last_contacted_by": null,
        "last_donated_at": "2014-02-02T11:51:23-05:00",
        "last_fundraised_at": "2014-01-01T11:51:23-05:00",
        "last_invoice_at": null,
        "last_rule_violation_at": null,
        "legal_name": null,
        "locale": "en",
        "mailing_address": null,
        "marital_status": "S",
        "media_market_name": null,
        "meetup_address": null,
        "middle_name": "T.",
        "mobile_normalized": null,
        "nbec_precinct_code": null,
        "note_updated_at": "2014-01-01T11:51:23-05:00",
        "outstanding_invoices_amount_in_cents": null,
        "outstanding_invoices_count": null,
        "overdue_invoices_count": 0,
        "page_slug": null,
        "parent": null,
        "parent_id": null,
        "party_member": false,
        "phone_normalized": null,
        "phone_time": "daytime",
        "precinct_code": "9876",
        "precinct_name": "9876",
        "prefix": null,
        "previous_party": "U",
        "primary_email_id": 1,
        "priority_level": 4,
        "priority_level_changed_at": null,
        "profile_content": "I support Abraham Lincoln for President.",
        "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
        "profile_headline": "Abe is back!",
        "received_capital_amount_in_cents": 0,
        "recruiter": {
            "birthdate": "1963-02-02",
            "city_district": null,
            "civicrm_id": 9,
            "county_district": "11",
            "county_file_id": "97076395",
            "created_at": "2014-02-02T11:51:23-05:00",
            "do_not_call": false,
            "do_not_contact": false,
            "dw_id": null,
            "email": null,
            "email_opt_in": true,
            "employer": "Sun Film Foundation",
            "external_id": "781986",
            "federal_district": "0",
            "fire_district": null,
            "first_name": "Mina",
            "has_facebook": false,
            "id": 233,
            "is_twitter_follower": false,
            "is_volunteer": false,
            "judicial_district": null,
            "labour_region": null,
            "last_name": "Abbott",
            "linkedin_id": null,
            "mobile": "5738882938",
            "mobile_opt_in": true,
            "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
            "ngp_id": null,
            "note": "Has 3 kids. Ask about the baby on the way",
            "occupation": "Community Organizer",
            "party": "P",
            "pf_strat_id": 91207702,
            "phone": "2156726335",
            "precinct_id": null,
            "primary_address": null,
            "profile_image_url_ssl": null,
            "recruiter_id": null,
            "rnc_id": 2653431,
            "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
            "salesforce_id": null,
            "school_district": "Chicago Public Schools",
            "school_sub_district": null,
            "sex": "F",
            "signup_type": 0,
            "state_file_id": "100000012",
            "state_lower_district": "024",
            "state_upper_district": "1",
            "support_level": 1,
            "supranational_district": "Eastern Euro Region",
            "tags": [],
            "twitter_id": "63403772",
            "twitter_name": "AngryPig",
            "updated_at": "2014-02-02T11:51:23-05:00",
            "van_id": "2",
            "village_district": null
        },
        "recruits_count": 0,
        "registered_address": null,
        "registered_at": null,
        "religion": null,
        "rule_violations_count": 0,
        "spent_capital_amount_in_cents": 0,
        "submitted_address": "123 Main St Portland, ME 04101",
        "subnations": ["abeforprez", "operalovers"],
        "suffix": null,
        "support_level_changed_at": "2014-02-02T11:51:23-05:00",
        "support_probability_score": null,
        "turnout_probability_score": null,
        "twitter_address": null,
        "twitter_description": "Animal lover.",
        "twitter_followers_count": 564,
        "twitter_friends_count": 32,
        "twitter_location": "Dallas, TX",
        "twitter_login": "trinity",
        "twitter_updated_at": "2014-01-01T11:51:23-05:00",
        "twitter_website": "http://mytwittersite.com",
        "unsubscribed_at": null,
        "user_submitted_address": null,
        "username": null,
        "warnings_count": 0,
        "website": null,
        "work_address": null,
        "work_phone_number": null
    },
    "precinct": {
        "id": 77,
        "code": "9876",
        "name": "9876"
    }
}

Search Endpoint

Use this endpoint to find people that have certain attributes.

GET /api/v1/people/search

Parameters

first_name - first name search parameter
last_name - last name search parameter
email - email address search parameter
city - city of the primary address of people to match
state - state of the primary address of people to match
sex - sex of the people to match (optional, M or F)
birthdate - date of birth of the people to match
updated_since - people updated since the given date
with_mobile - only people with mobile phone numbers
custom_values - match custom field values. It takes a nested format, e.g. {"custom_values": {"my_field_slug": "abcd"}}. In the query string this parameter would have to be encoded as custom_values[my_field_slug]=abcd.
civicrm_id - civicrm_id of the person to match
county_file_id - countyfileid of the person to match
state_file_id - statefileid of the person to match
datatrust_id - datatrust_id of the person to match
dw_id - dw_id of the person to match
media_market_id - mediamarketid of the person to match
ngp_id - ngp_id of the person to match
pf_strat_id - pfstratid of the person to match
van_id - van_id of the person to match
salesforce_id - salesforce_id of the person to match
rnc_id - rnc_id of the person to match
rnc_regid - rnc_regid of the person to match
external_id - external_id of the person to match.
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/people/search?first_name=Byron&city=Beverly%20Hills&state=CA

Should give you a response like this:

{
  "next": "/api/v1/people/search?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m&first_name=Byron&city=Beverly%20Hills&state=CA",
  "prev": null,
  "results": [
    {
      "birthdate": "1973-04-04",
      "city_district": "city_district_1",
      "civicrm_id": 123489,
      "county_district": "county_district_1",
      "county_file_id": "mycountyfileid",
      "created_at": "2014-02-02T11:51:23-05:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": 987,
      "email": "[email protected]",
      "email_opt_in": true,
      "employer": "Texas Instruments",
      "external_id": "external",
      "federal_district": "federal_district_1",
      "fire_district": "fire_district_1",
      "first_name": "Byron",
      "has_facebook": true,
      "id": 10801,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": "judicial_district_1",
      "labour_region": "labour_region_1",
      "last_name": "Smith",
      "linkedin_id": "linkedinid",
      "mobile": "5738882938",
      "mobile_opt_in": true,
      "nbec_guid": "c4545",
      "ngp_id": "myngpid",
      "note": "Has 3 kids. Ask about the baby on the way",
      "occupation": "Programmer",
      "party": "P",
      "pf_strat_id": 876,
      "phone": "2156726335",
      "precinct_id": 995,
      "primary_address": {
        "address1": "123 Fake St",
        "address2": null,
        "address3": null,
        "city": "Beverly Hills",
        "state": "CA",
        "country_code": "US",
        "zip": "90201",
        "lat": 34.0502,
        "lng": -117.2478
      },
      "profile_image_url_ssl": null,
      "recruiter_id": 10800,
      "rnc_id": 1234567,
      "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": "salesforceid",
      "school_district": "school_district_1",
      "school_sub_district": "school_sub_district_1",
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "a12345z",
      "state_lower_district": "state_lower_district_1",
      "state_upper_district": "state_upper_district_1",
      "support_level": 1,
      "supranational_district": "region_abc",
      "tags": [],
      "twitter_id": "765",
      "twitter_name": "AngryPig",
      "updated_at": "2014-02-02T11:51:23-05:00",
      "van_id": "d6767",
      "village_district": "village_district_1"
    }
  ]
}

Nearby Endpoint

Use this endpoint to search for people near a location defined by latitude and longitude.

GET /api/v1/people/nearby

Parameters

location - origin of search in the format latitude,longitude (required)
distance - the radius in miles for which to include results (optional, default: 1 mile)
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

In order to search for people in the 'foobar' nation that live within a mile of Coors Field in Denver, issue a request like this:

GET https://foobar.nationbuilder.com/api/v1/people/nearby?location=34.0522,-118.2428&distance=1

You should receive a response like this:

{
  "next": "/api/v1/people/nearby?__nonce=3OUjEzI6iyybc1F3sk6YrQ&__token=ADGvBW9wM69kUiss1KqTIyVeQ5M6OwiL6ttexRFnHK9m&location=34.0522,-118.2428&distance=1",
  "prev": null,
  "results": [
    {
      "birthdate": "1973-04-04",
      "city_district": null,
      "civicrm_id": 7,
      "county_district": "11",
      "county_file_id": "97076395",
      "created_at": "2014-03-15T15:31:28-04:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": null,
      "email": "[email protected]",
      "email_opt_in": true,
      "employer": "Sun Film Foundation",
      "external_id": "781986",
      "federal_district": "0",
      "fire_district": null,
      "first_name": "Gracie",
      "has_facebook": false,
      "id": 11778,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": null,
      "labour_region": null,
      "last_name": "Leuschke",
      "linkedin_id": null,
      "mobile": "5738882938",
      "mobile_opt_in": true,
      "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
      "ngp_id": null,
      "note": "Has 3 kids. Ask about the baby on the way",
      "occupation": "Community Organizer",
      "party": "P",
      "pf_strat_id": 91207702,
      "phone": "2156726335",
      "precinct_id": null,
      "primary_address": {
        "address1": "21292 Ahmad Rds",
        "address2": null,
        "address3": null,
        "city": "Doyleburgh",
        "state": "Wyoming",
        "country_code": "US",
        "zip": "57314-7614",
        "lat": "34.0522",
        "lng": "-118.2428"
      },
      "profile_image_url_ssl": null,
      "recruiter_id": null,
      "rnc_id": 2653431,
      "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": null,
      "school_district": "Chicago Public Schools",
      "school_sub_district": null,
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "100000012",
      "state_lower_district": "024",
      "state_upper_district": "1",
      "support_level": 1,
      "supranational_district": "Eastern Euro Region",
      "tags": [],
      "twitter_id": "63403772",
      "twitter_name": "AngryPig",
      "updated_at": "2014-03-15T15:31:28-04:00",
      "van_id": "2",
      "village_district": null,
      "active_customer_expires_at": null,
      "active_customer_started_at": null,
      "author": null,
      "author_id": null,
      "auto_import_id": null,
      "availability": "anytime",
      "banned_at": null,
      "billing_address": null,
      "bio": "Specialist in management and business growth.",
      "call_status_id": 5,
      "call_status_name": "no-answer",
      "capital_amount_in_cents": 0,
      "children_count": 2,
      "church": "Liberty Church",
      "city_sub_district": "DOWNTOWN LOS ANGELES",
      "closed_invoices_amount_in_cents": null,
      "closed_invoices_count": null,
      "contact_status_id": 3,
      "contact_status_name": "Answered",
      "could_vote_status": -1,
      "demo": "W",
      "donations_amount_in_cents": 0,
      "donations_amount_this_cycle_in_cents": 0,
      "donations_count": 0,
      "donations_count_this_cycle": 0,
      "donations_pledged_amount_in_cents": 0,
      "donations_raised_amount_in_cents": 0,
      "donations_raised_amount_this_cycle_in_cents": 0,
      "donations_raised_count": 0,
      "donations_raised_count_this_cycle": 0,
      "donations_to_raise_amount_in_cents": 0,
      "email1": "[email protected]",
      "email1_is_bad": false,
      "email2": null,
      "email2_is_bad": false,
      "email3": null,
      "email3_is_bad": false,
      "email4": null,
      "email4_is_bad": false,
      "ethnicity": null,
      "facebook_address": null,
      "facebook_profile_url": "http://www.facebook.com/alice",
      "facebook_updated_at": "2014-02-25T11:22:12-04:00",
      "facebook_username": "alice",
      "fax_number": null,
      "federal_donotcall": false,
      "first_donated_at": "2013-02-25T11:22:12-04:00",
      "first_fundraised_at": "2013-12-15T11:22:12-04:00",
      "first_invoice_at": "2014-01-21T11:22:12-04:00",
      "first_prospect_at": "2013-10-25T11:22:12-04:00",
      "first_recruited_at": "2013-05-25T11:22:12-04:00",
      "first_supporter_at": "2014-03-15T15:31:28-04:00",
      "first_volunteer_at": "2014-01-11T11:22:12-04:00",
      "full_name": "Gracie Leuschke",
      "home_address": {
        "address1": "21292 Ahmad Rds",
        "address2": null,
        "address3": null,
        "city": "Doyleburgh",
        "state": "Wyoming",
        "country_code": "US",
        "zip": "57314-7614",
        "lat": "34.0522",
        "lng": "-118.2428"
      },
      "import_id": null,
      "inferred_party": "H",
      "inferred_support_level": 1,
      "invoice_payments_amount_in_cents": 0,
      "invoice_payments_referred_amount_in_cents": 0,
      "invoices_amount_in_cents": null,
      "invoices_count": null,
      "is_deceased": false,
      "is_donor": false,
      "is_fundraiser": false,
      "is_ignore_donation_limits": false,
      "is_leaderboardable": true,
      "is_mobile_bad": false,
      "is_possible_duplicate": false,
      "is_profile_private": false,
      "is_profile_searchable": true,
      "is_prospect": false,
      "is_supporter": true,
      "is_survey_question_private": false,
      "language": "EN",
      "last_call_id": 2378,
      "last_contacted_at": null,
      "last_contacted_by": null,
      "last_donated_at": "2014-02-02T11:51:23-05:00",
      "last_fundraised_at": "2014-01-01T11:51:23-05:00",
      "last_invoice_at": null,
      "last_rule_violation_at": null,
      "legal_name": null,
      "locale": "en",
      "mailing_address": null,
      "marital_status": "S",
      "media_market_name": null,
      "meetup_address": null,
      "middle_name": "T.",
      "mobile_normalized": null,
      "nbec_precinct_code": null,
      "note_updated_at": "2014-01-01T11:51:23-05:00",
      "outstanding_invoices_amount_in_cents": null,
      "outstanding_invoices_count": null,
      "overdue_invoices_count": 0,
      "page_slug": null,
      "parent": null,
      "parent_id": null,
      "party_member": false,
      "phone_normalized": null,
      "phone_time": "daytime",
      "precinct_code": null,
      "precinct_name": null,
      "prefix": null,
      "previous_party": "U",
      "primary_email_id": 1,
      "priority_level": 4,
      "priority_level_changed_at": null,
      "profile_content": "I support Abraham Lincoln for President.",
      "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
      "profile_headline": "Abe is back!",
      "received_capital_amount_in_cents": 0,
      "recruiter": null,
      "recruits_count": 0,
      "registered_address": null,
      "registered_at": null,
      "religion": null,
      "rule_violations_count": 0,
      "spent_capital_amount_in_cents": 0,
      "submitted_address": "123 Main St Portland, ME 04101",
      "subnations": ["abeforprez", "operalovers"],
      "suffix": null,
      "support_level_changed_at": "2014-01-01T11:51:23-05:00",
      "support_probability_score": null,
      "turnout_probability_score": null,
      "twitter_address": null,
      "twitter_description": "Animal lover.",
      "twitter_followers_count": 564,
      "twitter_friends_count": 32,
      "twitter_location": "Dallas, TX",
      "twitter_login": "trinity",
      "twitter_updated_at": "2014-01-01T11:51:23-05:00",
      "twitter_website": "http://mytwittersite.com",
      "unsubscribed_at": null,
      "user_submitted_address": null,
      "username": null,
      "warnings_count": 0,
      "website": null,
      "work_address": null,
      "work_phone_number": null
    }
  ]
}

Create Endpoint

This endpoint creates a person with the provided data. It returns a full representation of the person that was created. If the creation step fails, it returns an error.

POST /api/v1/people

Parameters

person - the resource of the person to be created

A person is considered valid with a name, a phone number or an email. If a person you create does not meet these criteria you will receive an error for a field called identity.

Example

Make the request:

POST /api/v1/people

With attached body content like this:

{
  "person": {
    "email": "[email protected]",
    "last_name": "Smith",
    "first_name": "Bob",
    "sex": "M",
    "signup_type": 0,
    "employer": "Dexter Labs",
    "party": "P",
    "registered_address": {
      "state": "TX",
      "country_code": "US"
    }
  }
}

You will receive a response of status 200, with response body like this:

{
  "person": {
    "birthdate": null,
    "city_district": null,
    "civicrm_id": null,
    "county_district": null,
    "county_file_id": null,
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": null,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": "Dexter Labs",
    "external_id": null,
    "federal_district": null,
    "fire_district": null,
    "first_name": "Bob",
    "has_facebook": false,
    "id": 9682,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": null,
    "labour_region": null,
    "last_name": "Smith",
    "linkedin_id": null,
    "mobile": null,
    "mobile_opt_in": true,
    "nbec_guid": null,
    "ngp_id": null,
    "note": null,
    "occupation": null,
    "party": "P",
    "pf_strat_id": null,
    "phone": null,
    "precinct_id": null,
    "primary_address": {
      "address1": null,
      "address2": null,
      "address3": null,
      "city": null,
      "state": "TX",
      "country_code": "US",
      "zip": null,
      "lat": null,
      "lng": null
    },
     "profile_image_url_ssl": null,
    "recruiter_id": null,
    "rnc_id": null,
    "rnc_regid": null,
    "salesforce_id": null,
    "school_district": null,
    "school_sub_district": null,
    "sex": "M",
    "signup_type": 0,
    "state_file_id": null,
    "state_lower_district": null,
    "state_upper_district": null,
    "support_level": null,
    "supranational_district": null,
    "tags": [],
    "twitter_id": null,
    "twitter_name": null,
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": null,
    "village_district": null,
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": null,
    "banned_at": null,
    "billing_address": null,
    "bio": null,
    "call_status_id": null,
    "call_status_name": null,
    "capital_amount_in_cents": 0,
    "children_count": 0,
    "church": null,
    "city_sub_district": null,
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": null,
    "contact_status_name": null,
    "could_vote_status": null,
    "demo": null,
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": null,
    "facebook_updated_at": null,
    "facebook_username": null,
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": null,
    "first_fundraised_at": null,
    "first_invoice_at": null,
    "first_prospect_at": null,
    "first_recruited_at": null,
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": null,
    "full_name": "Bob Smith",
    "home_address": null,
    "import_id": null,
    "inferred_party": null,
    "inferred_support_level": null,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": null,
    "last_call_id": null,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": null,
    "last_fundraised_at": null,
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": null,
    "mailing_address": null,
    "marital_status": null,
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": null,
    "mobile_normalized": null,
    "nbec_precinct_code": null,
    "note_updated_at": null,
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": null,
    "phone_normalized": null,
    "phone_time": null,
    "precinct_code": null,
    "precinct_name": null,
    "prefix": null,
    "previous_party": null,
    "primary_email_id": 1,
    "priority_level": null,
    "priority_level_changed_at": null,
    "profile_content": null,
    "profile_content_html": null,
    "profile_headline": null,
    "received_capital_amount_in_cents": 0,
    "recruiter": null,
    "recruits_count": 0,
    "registered_address": {
      "address1": null,
      "address2": null,
      "address3": null,
      "city": null,
      "state": "TX",
      "country_code": "US",
      "zip": null,
      "lat": null,
      "lng": null
    },
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": null,
    "subnations": [],
    "suffix": null,
    "support_level_changed_at": null,
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": null,
    "twitter_followers_count": null,
    "twitter_friends_count": null,
    "twitter_location": null,
    "twitter_login": null,
    "twitter_updated_at": null,
    "twitter_website": null,
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": null
}

Update Endpoint

This endpoint updates a person with the provided id to have the provided data. It returns a full representation of the updated person. If the update step fails, it returns an error.

PUT /api/v1/people/:id

Parameters

person - the resource attributes of the person to change

Example

Make this request (assuming you have a person with id 54):

PUT /api/v1/people/54

With request body like this:

{
  "person": {
    "first_name": "Joe",
    "email": "[email protected]",
    "phone": "303-555-0841"
  }
}

You will receive a response of status 201, with response body like this:

{
  "person": {
    "birthdate": "1973-04-04",
    "city_district": "city_district_1",
    "civicrm_id": 123489,
    "county_district": "county_district_1",
    "county_file_id": "mycountyfileid",
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": 987,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": "Texas Instruments",
    "external_id": "external",
    "federal_district": "federal_district_1",
    "fire_district": "fire_district_1",
    "first_name": "Joe",
    "has_facebook": true,
    "id": 54,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": "judicial_district_1",
    "labour_region": "labour_region_1",
    "last_name": "Smith",
    "linkedin_id": "linkedinid",
    "mobile": "213 3944 624",
    "mobile_opt_in": true,
    "nbec_guid": "c4545",
    "ngp_id": "myngpid",
    "note": "Has 3 kids. Ask about the baby on the way",
    "occupation": "Programmer",
    "party": "D",
    "pf_strat_id": 876,
    "phone": "303-555-0841",
    "precinct_id": 55,
    "primary_address": null,
     "profile_image_url_ssl": null,
    "recruiter_id": 89,
    "rnc_id": 1234567,
    "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
    "salesforce_id": "salesforceid",
    "school_district": "school_district_1",
    "school_sub_district": "school_sub_district_1",
    "sex": "F",
    "signup_type": 0,
    "state_file_id": "a12345z",
    "state_lower_district": "state_lower_district_1",
    "state_upper_district": "state_upper_district_1",
    "support_level": 1,
    "supranational_district": "region_abc",
    "tags": [],
    "twitter_id": "765",
    "twitter_name": "AngryPig",
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": "d6767",
    "village_district": "village_district_1",
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": "anytime",
    "banned_at": null,
    "billing_address": null,
    "bio": "Specialist in management and business growth.",
    "call_status_id": 5,
    "call_status_name": "no-answer",
    "capital_amount_in_cents": 0,
    "children_count": 2,
    "church": "Liberty Church",
    "city_sub_district": "DOWNTOWN LOS ANGELES",
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": 3,
    "contact_status_name": "Answered",
    "could_vote_status": 1,
    "demo": "W",
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": "http://www.facebook.com/profile.php?id=124071",
    "facebook_updated_at": "2014-02-25T11:22:12-04:00",
    "facebook_username": "alice",
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": "2013-02-02T11:51:23-05:00",
    "first_fundraised_at": "2013-04-02T11:51:23-05:00",
    "first_invoice_at": "2013-01-02T11:51:23-05:00",
    "first_prospect_at": "2013-11-02T11:51:23-05:00",
    "first_recruited_at": "2013-05-02T11:51:23-05:00",
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": "2013-05-02T11:51:23-05:00",
    "full_name": "Joe Smith",
    "home_address": null,
    "import_id": null,
    "inferred_party": "H",
    "inferred_support_level": 1,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": "EN",
    "last_call_id": 2378,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": "2014-02-02T11:51:23-05:00",
    "last_fundraised_at": "2014-01-01T11:51:23-05:00",
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": "en",
    "mailing_address": null,
    "marital_status": "S",
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": "T.",
    "mobile_normalized": "2133944624",
    "nbec_precinct_code": null,
    "note_updated_at": "2014-01-01T11:51:23-05:00",
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": false,
    "phone_normalized": "3035550841",
    "phone_time": "daytime",
    "precinct_code": "9876",
    "precinct_name": "9876",
    "prefix": null,
    "previous_party": "U",
    "primary_email_id": 1,
    "priority_level": 4,
    "priority_level_changed_at": null,
    "profile_content": "I support Abraham Lincoln for President.",
    "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
    "profile_headline": "Abe is back!",
    "received_capital_amount_in_cents": 0,
    "recruiter": {
      "birthdate": "1973-04-04",
      "city_district": null,
      "civicrm_id": 7,
      "county_district": "11",
      "county_file_id": "97076395",
      "created_at": "2014-02-02T11:51:23-05:00",
      "do_not_call": false,
      "do_not_contact": false,
      "dw_id": null,
      "email": null,
      "email_opt_in": true,
      "employer": "Sun Film Foundation",
      "external_id": "781986",
      "federal_district": "0",
      "fire_district": null,
      "first_name": "Mina",
      "has_facebook": false,
      "id": 89,
      "is_twitter_follower": false,
      "is_volunteer": false,
      "judicial_district": null,
      "labour_region": null,
      "last_name": "Abbott",
      "linkedin_id": null,
      "mobile": "5738882938",
      "mobile_opt_in": true,
      "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
      "ngp_id": null,
      "note": "Has 3 kids. Ask about the baby on the way",
      "occupation": "Community Organizer",
      "party": "P",
      "pf_strat_id": 91207702,
      "phone": "2156726335",
      "precinct_id": null,
      "primary_address": null,
      "profile_image_url_ssl": null,
      "recruiter_id": null,
      "rnc_id": 2653431,
      "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
      "salesforce_id": null,
      "school_district": "Chicago Public Schools",
      "school_sub_district": null,
      "sex": "F",
      "signup_type": 0,
      "state_file_id": "100000012",
      "state_lower_district": "024",
      "state_upper_district": "1",
      "support_level": 1,
      "supranational_district": "Eastern Euro Region",
      "tags": [],
      "twitter_id": "63403772",
      "twitter_name": "AngryPig",
      "updated_at": "2014-02-02T11:51:23-05:00",
      "van_id": "2",
      "village_district": null
    },
    "recruits_count": 0,
    "registered_address": null,
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": "123 Main St Portland, ME 04101",
    "subnations": ["abeforprez", "operalovers"],
    "suffix": null,
    "support_level_changed_at": "2014-02-02T11:51:23-05:00",
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": "Animal lover.",
    "twitter_followers_count": 564,
    "twitter_friends_count": 32,
    "twitter_location": "Dallas, TX",
    "twitter_login": "trinity",
    "twitter_updated_at": "2014-01-01T11:51:23-05:00",
    "twitter_website": "http://mytwittersite.com",
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": {
      "id": 55,
      "code": "9876",
      "name": "9876"
  }
}

Push Endpoint

This endpoint attempts to match the input person resource to a person already in the nation. If a match is found, the matched person is updated and a 200 status code is returned. If a match is not found, a new person is created and a 201 status code is returned. Matches are found by including one of the following IDs in the request:

civicrm_id
county_file_id
dw_id
external_id
email
facebook_username
ngp_id
salesforce_id
twitter_login
van_id

PUT /api/v1/people/push

Update Example

Assuming there is a person with the email address "[email protected]" in the foobar nation, this request:

PUT https://foobar.nationbuilder.com/api/v1/people/push

With this attached request body:

{
  "person": {
    "email": "[email protected]",
    "last_name": "Erastos",
    "sex": "M"
  }
}

Should update the existing record to have the new name and sex, return status code 200, and this body:

{
  "person": {
    "birthdate": "1973-04-04",
    "city_district": null,
    "civicrm_id": 7,
    "county_district": "11",
    "county_file_id": "97076395",
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": null,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": "Sun Film Foundation",
    "external_id": "781986",
    "federal_district": "0",
    "fire_district": null,
    "first_name": "Byron",
    "has_facebook": false,
    "id": 9232,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": null,
    "labour_region": null,
    "last_name": "Erastos",
    "linkedin_id": null,
    "mobile": "5738882938",
    "mobile_opt_in": true,
    "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
    "ngp_id": null,
    "note": "Has 3 kids. Ask about the baby on the way",
    "occupation": "Community Organizer",
    "party": "P",
    "pf_strat_id": 91207702,
    "phone": "2156726335",
    "precinct_id": null,
    "primary_address": null,
    "profile_image_url_ssl": null,
    "recruiter_id": null,
    "rnc_id": 2653431,
    "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
    "salesforce_id": null,
    "school_district": "Chicago Public Schools",
    "school_sub_district": null,
    "sex": "M",
    "signup_type": 0,
    "state_file_id": "100000012",
    "state_lower_district": "024",
    "state_upper_district": "1",
    "support_level": 1,
    "supranational_district": "Eastern Euro Region",
    "tags": [],
    "twitter_id": "63403772",
    "twitter_name": "AngryPig",
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": "2",
    "village_district": null,
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": "anytime",
    "banned_at": null,
    "billing_address": null,
    "bio": "Specialist in management and business growth.",
    "call_status_id": 5,
    "call_status_name": "no-answer",
    "capital_amount_in_cents": 0,
    "children_count": 2,
    "church": "Liberty Church",
    "city_sub_district": "DOWNTOWN LOS ANGELES",
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": 3,
    "contact_status_name": "Answered",
    "could_vote_status": -1,
    "demo": "W",
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": "http://www.facebook.com/alice",
    "facebook_updated_at": "2014-02-25T11:22:12-04:00",
    "facebook_username": "alice",
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": "2013-02-02T11:51:23-05:00",
    "first_fundraised_at": "2013-04-02T11:51:23-05:00",
    "first_invoice_at": "2013-01-02T11:51:23-05:00",
    "first_prospect_at": "2013-11-02T11:51:23-05:00",
    "first_recruited_at": "2013-05-02T11:51:23-05:00",
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": "2013-05-02T11:51:23-05:00",
    "full_name": "Byron Erastos",
    "home_address": null,
    "import_id": null,
    "inferred_party": "H",
    "inferred_support_level": 1,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": "EN",
    "last_call_id": 2378,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": "2014-02-02T11:51:23-05:00",
    "last_fundraised_at": "2014-01-01T11:51:23-05:00",
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": "en",
    "mailing_address": null,
    "marital_status": "S",
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": "T.",
    "mobile_normalized": null,
    "nbec_precinct_code": null,
    "note_updated_at": "2014-01-01T11:51:23-05:00",
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": false,
    "phone_normalized": null,
    "phone_time": "daytime",
    "precinct_code": null,
    "precinct_name": null,
    "prefix": null,
    "previous_party": "U",
    "primary_email_id": 1,
    "priority_level": 4,
    "priority_level_changed_at": null,
    "profile_content": "I support Abraham Lincoln for President.",
    "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
    "profile_headline": "Abe is back!",
    "received_capital_amount_in_cents": 0,
    "recruiter": null,
    "recruits_count": 0,
    "registered_address": null,
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": "123 Main St Portland, ME 04101",
    "subnations": ["abeforprez", "operalovers"],
    "suffix": null,
    "support_level_changed_at": "2014-01-01T11:51:23-05:00",
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": "Animal lover.",
    "twitter_followers_count": 564,
    "twitter_friends_count": 32,
    "twitter_location": "Dallas, TX",
    "twitter_login": "trinity",
    "twitter_updated_at": "2014-01-01T11:51:23-05:00",
    "twitter_website": "http://mytwittersite.com",
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": null
}

Creation example

Assuming there is no matching person in the foobar nation, make the request:

PUT https://foobar.nationbuilder.com/api/v1/people/push

With this attached request body:

{
  "person": {
    "email": "[email protected]",
    "first_name": "Byron",
    "last_name": "Erastos",
    "sex": "M"
  }
}

A new record will be created with the provided attributes and you will receive a response of status 201, with response body like this:

{
  "person": {
    "birthdate": null,
    "city_district": null,
    "civicrm_id": null,
    "county_district": null,
    "county_file_id": null,
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": null,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": null,
    "external_id": null,
    "federal_district": null,
    "fire_district": null,
    "first_name": "Byron",
    "has_facebook": false,
    "id": 9232,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": null,
    "labour_region": null,
    "last_name": "Erastos",
    "linkedin_id": null,
    "mobile": null,
    "mobile_opt_in": true,
    "nbec_guid": null,
    "ngp_id": null,
    "note": null,
    "occupation": null,
    "party": null,
    "pf_strat_id": null,
    "phone": null,
    "precinct_id": null,
    "primary_address": null,
     "profile_image_url_ssl": null,
    "recruiter_id": null,
    "rnc_id": null,
    "rnc_regid": null,
    "salesforce_id": null,
    "school_district": null,
    "school_sub_district": null,
    "sex": "M",
    "signup_type": 0,
    "state_file_id": null,
    "state_lower_district": null,
    "state_upper_district": null,
    "support_level": null,
    "supranational_district": null,
    "tags": [],
    "twitter_id": null,
    "twitter_name": null,
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": null,
    "village_district": null,
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": null,
    "banned_at": null,
    "billing_address": null,
    "bio": null,
    "call_status_id": null,
    "call_status_name": null,
    "capital_amount_in_cents": 0,
    "children_count": 0,
    "church": null,
    "city_sub_district": null,
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": null,
    "contact_status_name": null,
    "could_vote_status": null,
    "demo": null,
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": null,
    "facebook_updated_at": null,
    "facebook_username": null,
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": null,
    "first_fundraised_at": null,
    "first_invoice_at": null,
    "first_prospect_at": null,
    "first_recruited_at": null,
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": null,
    "full_name": "Byron Erastos",
    "home_address": null,
    "import_id": null,
    "inferred_party": null,
    "inferred_support_level": null,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": null,
    "last_call_id": null,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": null,
    "last_fundraised_at": null,
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": null,
    "mailing_address": null,
    "marital_status": null,
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": null,
    "mobile_normalized": null,
    "nbec_precinct_code": null,
    "note_updated_at": null,
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": null,
    "phone_normalized": null,
    "phone_time": null,
    "precinct_code": null,
    "precinct_name": null,
    "prefix": null,
    "previous_party": null,
    "primary_email_id": 1,
    "priority_level": null,
    "priority_level_changed_at": null,
    "profile_content": null,
    "profile_content_html": null,
    "profile_headline": null,
    "received_capital_amount_in_cents": 0,
    "recruiter": null,
    "recruits_count": 0,
    "registered_address": null,
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": null,
    "subnations": [],
    "suffix": null,
    "support_level_changed_at": null,
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": null,
    "twitter_followers_count": null,
    "twitter_friends_count": null,
    "twitter_location": null,
    "twitter_login": null,
    "twitter_updated_at": null,
    "twitter_website": null,
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": null
}

Destroy Endpoint

This endpoint removes a person with the provided id from nation. It takes no parameters and returns response code 204 on success.

DELETE /api/v1/people/:id

Register Endpoint

This endpoint starts a user registration process for the given person by sending an account confirmation email.

GET /api/v1/people/:id/register

Example

Assuming a person with id 123 exists in foobar nation, make the request:

GET https://foobar.nationbuilder.com/api/v1/people/123/register

You will receive a response body like this:

{
  "status": "success"
}

Success means that the account activation email was sent successfully.

Me Endpoint

This endpoint returns the access token's resource owner's representation.

GET /api/v1/people/me

Example

Make the request:

GET https://foobar.nationbuilder.com/api/v1/people/me

You will receive a response of status 200 and a body like this:

{
  "person": {
    "birthdate": "1973-04-04",
    "city_district": null,
    "civicrm_id": 7,
    "county_district": "11",
    "county_file_id": "97076395",
    "created_at": "2014-02-02T11:51:23-05:00",
    "do_not_call": false,
    "do_not_contact": false,
    "dw_id": null,
    "email": "[email protected]",
    "email_opt_in": true,
    "employer": "Sun Film Foundation",
    "external_id": "781986",
    "federal_district": "0",
    "fire_district": null,
    "first_name": "Gracie",
    "has_facebook": false,
    "id": 76,
    "is_twitter_follower": false,
    "is_volunteer": false,
    "judicial_district": null,
    "labour_region": null,
    "last_name": "Leuschke",
    "linkedin_id": null,
    "mobile": "5738882938",
    "mobile_opt_in": true,
    "nbec_guid": "000099dc-00f0-11e2-b349-27c4eb6c1979",
    "ngp_id": null,
    "note": "Has 3 kids. Ask about the baby on the way",
    "occupation": "Community Organizer",
    "party": "P",
    "pf_strat_id": 91207702,
    "phone": "2156726335",
    "precinct_id": null,
    "primary_address": null,
     "profile_image_url_ssl": null,
    "recruiter_id": null,
    "rnc_id": 2653431,
    "rnc_regid": "003F4ED9-3C5C-4E15-8178-B84920F41BFF",
    "salesforce_id": null,
    "school_district": "Chicago Public Schools",
    "school_sub_district": null,
    "sex": "F",
    "signup_type": 0,
    "state_file_id": "100000012",
    "state_lower_district": "024",
    "state_upper_district": "1",
    "support_level": 1,
    "supranational_district": "Eastern Euro Region",
    "tags": [],
    "twitter_id": "63403772",
    "twitter_name": "AngryPig",
    "updated_at": "2014-02-02T11:51:23-05:00",
    "van_id": "2",
    "village_district": null,
    "active_customer_expires_at": null,
    "active_customer_started_at": null,
    "author": null,
    "author_id": null,
    "auto_import_id": null,
    "availability": "anytime",
    "banned_at": null,
    "billing_address": null,
    "bio": "Specialist in management and business growth.",
    "call_status_id": 5,
    "call_status_name": "no-answer",
    "capital_amount_in_cents": 0,
    "children_count": 2,
    "church": "Liberty Church",
    "city_sub_district": "DOWNTOWN LOS ANGELES",
    "closed_invoices_amount_in_cents": null,
    "closed_invoices_count": null,
    "contact_status_id": 3,
    "contact_status_name": "Answered",
    "could_vote_status": -1,
    "demo": "W",
    "donations_amount_in_cents": 0,
    "donations_amount_this_cycle_in_cents": 0,
    "donations_count": 0,
    "donations_count_this_cycle": 0,
    "donations_pledged_amount_in_cents": 0,
    "donations_raised_amount_in_cents": 0,
    "donations_raised_amount_this_cycle_in_cents": 0,
    "donations_raised_count": 0,
    "donations_raised_count_this_cycle": 0,
    "donations_to_raise_amount_in_cents": 0,
    "email1": "[email protected]",
    "email1_is_bad": false,
    "email2": null,
    "email2_is_bad": false,
    "email3": null,
    "email3_is_bad": false,
    "email4": null,
    "email4_is_bad": false,
    "ethnicity": null,
    "facebook_address": null,
    "facebook_profile_url": "http://www.facebook.com/alice",
    "facebook_updated_at": "2014-02-25T11:22:12-04:00",
    "facebook_username": "alice",
    "fax_number": null,
    "federal_donotcall": false,
    "first_donated_at": "2013-02-02T11:51:23-05:00",
    "first_fundraised_at": "2013-04-02T11:51:23-05:00",
    "first_invoice_at": "2013-01-02T11:51:23-05:00",
    "first_prospect_at": "2013-11-02T11:51:23-05:00",
    "first_recruited_at": "2013-05-02T11:51:23-05:00",
    "first_supporter_at": "2014-02-02T11:51:23-05:00",
    "first_volunteer_at": "2013-05-02T11:51:23-05:00",
    "full_name": "Gracie Leuschke",
    "home_address": null,
    "import_id": null,
    "inferred_party": "H",
    "inferred_support_level": 1,
    "invoice_payments_amount_in_cents": 0,
    "invoice_payments_referred_amount_in_cents": 0,
    "invoices_amount_in_cents": null,
    "invoices_count": null,
    "is_deceased": false,
    "is_donor": false,
    "is_fundraiser": false,
    "is_ignore_donation_limits": false,
    "is_leaderboardable": true,
    "is_mobile_bad": false,
    "is_possible_duplicate": false,
    "is_profile_private": false,
    "is_profile_searchable": true,
    "is_prospect": false,
    "is_supporter": true,
    "is_survey_question_private": false,
    "language": "EN",
    "last_call_id": 2378,
    "last_contacted_at": null,
    "last_contacted_by": null,
    "last_donated_at": "2014-02-02T11:51:23-05:00",
    "last_fundraised_at": "2014-01-01T11:51:23-05:00",
    "last_invoice_at": null,
    "last_rule_violation_at": null,
    "legal_name": null,
    "locale": "en",
    "mailing_address": null,
    "marital_status": "S",
    "media_market_name": null,
    "meetup_address": null,
    "middle_name": "T.",
    "mobile_normalized": null,
    "nbec_precinct_code": null,
    "note_updated_at": "2014-01-01T11:51:23-05:00",
    "outstanding_invoices_amount_in_cents": null,
    "outstanding_invoices_count": null,
    "overdue_invoices_count": 0,
    "page_slug": null,
    "parent": null,
    "parent_id": null,
    "party_member": false,
    "phone_normalized": null,
    "phone_time": "daytime",
    "precinct_code": null,
    "precinct_name": null,
    "prefix": null,
    "previous_party": "U",
    "primary_email_id": 1,
    "priority_level": 4,
    "priority_level_changed_at": null,
    "profile_content": "I support Abraham Lincoln for President.",
    "profile_content_html": "<p>I support Abraham Lincoln for President.</p>",
    "profile_headline": "Abe is back!",
    "received_capital_amount_in_cents": 0,
    "recruiter": null,
    "recruits_count": 0,
    "registered_address": null,
    "registered_at": null,
    "religion": null,
    "rule_violations_count": 0,
    "spent_capital_amount_in_cents": 0,
    "submitted_address": "123 Main St Portland, ME 04101",
    "subnations": ["abeforprez", "operalovers"],
    "suffix": null,
    "support_level_changed_at": "2014-01-01T11:51:23-05:00",
    "support_probability_score": null,
    "turnout_probability_score": null,
    "twitter_address": null,
    "twitter_description": "Animal lover.",
    "twitter_followers_count": 564,
    "twitter_friends_count": 32,
    "twitter_location": "Dallas, TX",
    "twitter_login": "trinity",
    "twitter_updated_at": "2014-01-01T11:51:23-05:00",
    "twitter_website": "http://mytwittersite.com",
    "unsubscribed_at": null,
    "user_submitted_address": null,
    "username": null,
    "warnings_count": 0,
    "website": null,
    "work_address": null,
    "work_phone_number": null
  },
  "precinct": null
}

Lists

This endpoint returns all lists a person belongs to.

GET /api/v1/people/:person_id/lists

Taggings

This endpoint returns all tags applied to a person.

GET /api/v1/people/:person_id/taggings

Tag Person

This endpoint applies one or more tags to a person.

PUT /api/v1/people/:person_id/taggings

Example request bodies

{
  "tagging": {
    "tag": "my_tag"
  }
}

{
  "tagging": {
    "tag": ["my_tag1", "my_tag2"]
  }
}

Tag Removal

This endpoint removes a single tag from a person.

DELETE /api/v1/people/:person_id/taggings/:tag_name

Batch Tag Removal

This endpoint removes one or more tags from a person.

DELETE /api/v1/people/:person_id/taggings

Example request bodies

{
  "tagging": {
    "tag": "my_tag"
  }
}

{
  "tagging": {
    "tag": ["my_tag1", "my_tag2"]
  }
}

Private Notes

Create

POST /api/v1/people/:person_id/notes

Example

{
  "note": {
    "content": "Seems likely to be a supporter"
  }
}

Custom Fields

Custom fields can be set in the API, and will also be included in all person resource responses.

See documentation for custom fields on the API for more details.

If you have suggestions for these docs, they are public on Github and we accept pull requests.