Dartmouth API Developer Portal

People-Contacts API

GET returns information about contacts for a person. PUT allows contacts to be created, updated, or deleted. (Currently limited to people who are students.)

The People-Contacts API draws on multiple sources, currently Banner for student contacts and HRMS for employees. Only student contacts are updateable through this API. Contacts that are not updatable have the readonly other attribute set.

Each contact is labeled with a contact_type_id. The full list of all contact_type_ids are in the /api/contact_types endpoint.

Rating

Attribute	Value
Highly Available	Yes
Cache Refresh Interval	60 minutes
Filtering	Yes
Read	Yes
Write	Yes for particular types

GET

GET returns all contacts for the specified netid.

Required Scopes

Scope	Description
urn:dartmouth:people:read.sensitive	This scope is required to access people contacts. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:private	This optional scope is required in order to view contacts for FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office

Request

GET /api/people/{netid}/contacts

Required Headers

Authorization: Bearer {jwt}

Parameters

Parameter Name	Type	Description	Valid values	Required

(Standard filter parameters)

Notes on usage

Contacts are modeled as a subresource of people. Currently it is only possible to get contacts for a particular person. Searching for holders of certain contacts is not available.

The contacts are returned as a collection. When the person does not have contacts associated with their account a status of 200 is returned with an empty array in the payload.

Returns

Status Code	Description
200	The URI parameter {netid} passed in is a valid identity
404	The URI parameter {netid} passed in is NOT a valid identity

Sample Request

https://api.dartmouth.edu/api/people/d10073q/contacts

Sample Return of Student Contacts

[
    {
        "owner_netid": "f00000x",
        "contact": {
            "contact_type_id": "EMRG",
            "priority": "1",
            "personal_relationship_id": "M",
            "last_name": "Doe",
            "first_name": "Jane",
            "middle_name": null,
            "email": "jdlata@gmail.com",
            "addresses": [
                {
                    "street_line_1": "412 514th Street, Unit X",
                    "street_line_2": null,
                    "street_line_3": null,
                    "city": "Mount Hunger",
                    "state_id": "WA",
                    "country_id": null,
                    "postal_code": "98000",
                    "address_type_id": null,
                    "from_date": null,
                    "to_date": null
                }
            ],
            "telephone_numbers": [
                {
                    "area_code": "855",
                    "number": "6665555",
                    "extension": null,
                    "country_id": null,
                    "is_international": null,
                    "telephone_type_id": null,
                    "from_date": null,
                    "to_date": null
                }
            ],
            "data_origin": "Banner",
            "data_source": "sis"
        },
        "id": "5cc30e50129f9a54569f8a10",
        "cache_date": "2019-05-24T17:36:36Z"
    },
    {
        "owner_netid": "f00000x",
        "contact": {
            "contact_type_id": "XP",
            "personal_relationship_id": "F",
            "middle_name": "D",
            "priority": "9",
            "last_name": "Doe",
            "first_name": "John",
            "addresses": [
                {
                    "street_line_1": null,
                    "city": null,
                    "to_date": null,
                    "street_line_3": null,
                    "street_line_2": null,
                    "from_date": null,
                    "country_id": null,
                    "postal_code": null,
                    "state_id": null,
                    "address_type_id": "XP"
                }
            ],
            "email": "jdd@gmail.com",
            "telephone_numbers": [
                {
                    "extension": null,
                    "telephone_type_id": null,
                    "area_code": "777",
                    "country_id": null,
                    "from_date": null,
                    "number": "5554444",
                    "to_date": null,
                    "is_international": null
                }
            ],
            "data_origin": "Banner",
            "data_source": "sis"
        },
        "id": "5cc30e56129f9a54569fa787",
        "cache_date": "2019-05-24T18:11:50Z"
    }]

Sample Return of Employee Contacts

[
    {
        "owner_netid": "d33xxxy",
        "contact": {
            "contact_type_id": "HRSEMRG",
            "telephone_numbers": [
                {
                    "number_type": "primary",
                    "number": "555.656.8974"
                },
                {
                    "number_type": "alternative",
                    "number": "555.329.8186"
                }
            ],
            "name": "Jane Doe",
            "priority": "1",
            "other_attributes": [
                {
                    "name": "readonly"
                }
            ],
            "data_origin": null,
            "data_source": "hrs"
        },
        "id": "5d49ce16fffdae2b58d1696b",
        "cache_date": "2019-08-07T19:40:38Z"
    }
]

PUT

PUT completely replaces contacts for the specified netid. It will create, update, or delete contacts so that current contacts for the associated person match the payload exactly.

Required Scopes

Scope	Description
urn:dartmouth:people:write.sensitive	This scope is required in order to write contacts. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:read.sensitive	This scope is required in order to release contact attributes; both read and write scopes are required. Granting of this scope is approved by the Chief Technology Officer of ITC
urn:dartmouth:people:private	This optional scope is required in order to update contacts for FERPA protected identities. Granting of this scope is via the Undergraduate Registrars Office

Request

PUT /api/people/{netid}/contacts

Required Headers

Authorization: Bearer {jwt}
Content-Type: application/json

Payload

PUT payload must be included in the request body. All current contacts must be included and all attributes - minus data_source and data_origin - must be included for each contact. Here is an example payload:

[
    {
        "owner_netid": "f00000x",
        "contact": {
            "contact_type_id": "EMRG",
            "priority": "1",
            "personal_relationship_id": "M",
            "last_name": "Jane",
            "first_name": "Doe",
            "middle_name": null,
            "email": "jd@gmail.com",
            "addresses": [
                {
                    "street_line_1": "412 412th Street, Unit Z",
                    "street_line_2": null,
                    "street_line_3": null,
                    "city": "Mount Vernon",
                    "state_id": "NH",
                    "country_id": null,
                    "postal_code": "01234",
                    "address_type_id": null,
                    "from_date": null,
                    "to_date": null
                }
            ],
            "telephone_numbers": [
                {
                    "area_code": "802",
                    "number": "7284355",
                    "extension": null,
                    "country_id": null,
                    "is_international": null,
                    "telephone_type_id": null,
                    "from_date": null,
                    "to_date": null
                }
            ]
        }
    },
    {
        "owner_netid": "f00000x",
        "contact": {
            "contact_type_id": "XP",
            "priority": "9",
            "personal_relationship_id": "F",
            "last_name": "Doe",
            "first_name": "John",
            "middle_name": "D",
            "email": "jdd@gmail.com",
            "addresses": [
                {
                    "street_line_1": null,
                    "street_line_2": null,
                    "street_line_3": null,
                    "city": null,
                    "state_id": null,
                    "country_id": null,
                    "postal_code": null,
                    "address_type_id": "XP",
                    "from_date": null,
                    "to_date": null
                }
            ],
            "telephone_numbers": [
                {
                    "area_code": "802",
                    "number": "7284355",
                    "extension": null,
                    "country_id": null,
                    "is_international": null,
                    "telephone_type_id": null,
                    "from_date": null,
                    "to_date": null
                }
            ]
        }
    }
]

Note that addresses and telephone_numbers are arrays, but only 1 array item is allowed.

Field	Type	Description
owner_netid	string	Must be equal to {netid} URI parameter
contact.contact_type_id	string	Must be a valid contact_type id (from /contact_types API)
contact.priority	string	Must be an integer value
contact.personal_relationship_id	string	Must be a valid personal_relationship id (from /personal_relationship_types API)
contact.first_name	string	Cannot be null
contact.last_name	string	Cannot be null
contact.middle_name	string
contact.email	string
contact.addresses[0].street_line_1	string
contact.addresses[0].street_line_2	string
contact.addresses[0].street_line_3	string
contact.addresses[0].city	string
contact.addresses[0].state_id	string	Must be a valid state id (from /states API) or null
contact.addresses[0].country_id	string	Must be a valid country id (from /countries API) or null
contact.addresses[0].postal_code	string
contact.addresses[0].address_type_id	string	Must be a valid address_type id (from /address_types API) or null
contact.addresses[0].from_date	string	(ignored)
contact.addresses[0].to_date	string	(ignored)
contact.telephone_numbers[0].area_code	string
contact.telephone_numbers[0].number	string
contact.telephone_numbers[0].extension	string
contact.telephone_numbers[0].country_id	string	(ignored)
contact.telephone_numbers[0].is_international	boolean	(ignored)
contact.telephone_numbers[0].telephone_type_id	string	(ignored)
contact.telephone_numbers[0].from_date	string	(ignored)
contact.telephone_numbers[0].to_date	string	(ignored)

Notes on usage

The people-contacts API checks the validity of the payload, the presence of required scopes, and confirms that the requested people record exists. It then submits the request to a task queue and returns the url of the task in the location header. The consumer must poll the task until completion.

The task will create, update, or delete contacts so that current contacts for the person match the payload exactly.

Returns

Status Code	Description
202	The URI parameter {netid} passed in is a valid identity, request payload is valid, and the required scopes are in place
404	The URI parameter {netid} passed in is NOT a valid identity
400	Invalid attributes in payload

Sample Request

https://api.dartmouth.edu/api/people/d10073q/contacts

Sample Return

{
    "status": "accepted"
}

Sample Response Header

Location: /api/tasks/5cddb466b68a450c3b102bfd

Task Monitoring

After a PUT request has been accepted, the consumer must poll the task until completion using the following request:

GET /api/tasks/{id}

Here is an example using the task id from above:

https://api.dartmouth.edu/api/tasks/5cddb466b68a450c3b102bfd

Sample Incomplete Task

For incomplete tasks, path is null:

{
    "status": "accepted",
    "path": null,
    "id": "5cddb466b68a450c3b102bfd"
}

Sample Successful Task

For successfully completed tasks, path is set to the url of the resource that was updated and status provides details of the operation(s) completed.

{
    "status": "SUCCESS: 2 contacts added for f00000x",
    "path": "https://api-dev.dartmouth.edu/api/people/d23854z/contacts",
    "id": "5cddb466b68a450c3b102bfd"
}

Sample Failed Task

For failed tasks, path is set to the url of the resource that was supposed to be updated and status provides details of the failure.

{
    "status": "FAILURE: invalid json payload: [{'owner_netid': 'f00000xx', 'contact': {'contact_type_id': 'EMRG', 'priority': '3', 'personal_relationship_id': 'F', 'last_name': 'Lata', 'first_name': 'Emmanuel', 'middle_name': 'A', 'email': 'manny.lata66@gmail.com', 'addresses': [{'street_line_1': '4126 214th Street, Unit C', 'street_line_2': None, 'street_line_3': None, 'city': 'Mountlake Terrace', 'state_id': 'WA', 'country_id': 'US', 'postal_code': '98043', 'address_type_id': None, 'from_date': None, 'to_date': None}], 'telephone_numbers': [{'area_code': '858', 'number': '4728971', 'extension': '4728971', 'country_id': None, 'is_international': None, 'telephone_type_id': None, 'from_date': None, 'to_date': None}]}}, {'owner_netid': 'f00000x', 'contact': {'contact_type_id': 'EMRG', 'priority': '2', 'personal_relationship_id': 'F', 'last_name': 'Lata', 'first_name': 'Maxwell', 'middle_name': None, 'email': 'maxwell.a.lata.20@dartmouth.edu', 'addresses': [{'street_line_1': '4126 214th Street, Unit C', 'street_line_2': None, 'street_line_3': None, 'city': 'Mountlake Terrace', 'state_id': 'WA', 'country_id': 'US', 'postal_code': '98043', 'address_type_id': None, 'from_date': None, 'to_date': None}], 'telephone_numbers': [{'area_code': '858', 'number': '8295461', 'extension': None, 'country_id': None, 'is_international': None, 'telephone_type_id': None, 'from_date': None, 'to_date': None}]}}, {'owner_netid': 'f00000x', 'contact': {'contact_type_id': 'EMRG', 'priority': '1', 'personal_relationship_id': 'M', 'last_name': 'Lata', 'first_name': 'Stacy', 'middle_name': None, 'email': 'stacy.lata@gmail.com', 'addresses': [{'street_line_1': '4126 214th Street, Unit C', 'street_line_2': None, 'street_line_3': None, 'city': 'Mountlake Terrace', 'state_id': 'WA', 'country_id': None, 'postal_code': '98043', 'address_type_id': None, 'from_date': None, 'to_date': None}], 'telephone_numbers': [{'area_code': '858', 'number': '8295973', 'extension': None, 'country_id': None, 'is_international': None, 'telephone_type_id': None, 'from_date': None, 'to_date': None}]}}, {'owner_netid': 'f00000x', 'contact': {'contact_type_id': 'XP', 'priority': '9', 'personal_relationship_id': 'F', 'last_name': 'Lata', 'first_name': 'Emmanuel', 'middle_name': 'D', 'email': 'manny.lata66@gmail.com', 'addresses': [{'street_line_1': None, 'street_line_2': None, 'street_line_3': None, 'city': None, 'state_id': None, 'country_id': None, 'postal_code': None, 'address_type_id': 'XP', 'from_date': None, 'to_date': None}], 'telephone_numbers': [{'area_code': '858', 'number': '4728971', 'extension': None, 'country_id': None, 'is_international': None, 'telephone_type_id': None, 'from_date': None, 'to_date': None}]}}]",
    "path": "https://api-dev.dartmouth.edu/api/people/f00000x/contacts",
    "id": "5cddb466b68a450c3b102bfd"
}