Discussions
Product Notice: Eloqua Application API contact endpoints – Adding "accountId" when contact is linked
With the arrival of Eloqua release 20A (Feb 2020), accountId will be returned at complete depth when retrieving, creating, or updating Contacts using the Application API when the Contact is linked to an Account.
What’s changing?
With 20A, accountId will be returned at complete depth when the Contact is linked to an Account when using the following Application API endpoints:
- 1.0
- Retrieve a contact: GET /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Retrieve a list of contacts: GET /api/REST/1.0/data/contacts
- Default depth is minimal
- Create a contact: POST /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Update a contact: PUT /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Retrieve a contact: GET /api/REST/1.0/data/contact/{id}
- 2.0
- Retrieve contact information: POST /api/REST/2.0/data/contacts
- Default depth is minimal
- Retrieve contact information: POST /api/REST/2.0/data/contacts
Notes:
- accountId will be returned when creating the Contact if the Contact field selected for Account Linkage has a value for an existing Account
- accountId will be returned when updating the Contact:
- If the Contact field selected for Account Linkage is being changed and has a value for an existing Account
- If the Contact field selected for Account Linkage is not being changed, and that Contact is already linked to an Account
Example
Prior to 20A, accountId is not returned:
Request:
GET /api/REST/1.0/data/contact/3
Response: 200 OK
{
"type": "Contact",
"currentStatus": "Awaiting action",
"id": "3",
"createdAt": "1551283355",
"depth": "complete",
"name": "[email protected]",
"updatedAt": "1569363574",
"accountName": "Eloqua",
"city": "Test",
"emailAddress": "[email protected]",
"emailFormatPreference": "unspecified",
"fieldValues": [...],
"firstName": "Account",
"isBounceback": "false",
"isSubscribed": "true",
"lastName": "Linked",
"subscriptionDate": "1551283355"
}
After 20A, accountId will now be returned:
Request:
GET GET /api/REST/1.0/data/contact/3
Response: 200 OK
{
"type": "Contact",
"currentStatus": "Awaiting action",
"id": "3",
"createdAt": "1551283355",
"depth": "complete",
"name": "[email protected]",
"updatedAt": "1569363574",
"accountId": "43",
"accountName": "Eloqua",
"city": "Test",
"emailAddress": "[email protected]",
"emailFormatPreference": "unspecified",
"fieldValues": [...],
"firstName": "Account",
"isBounceback": "false",
"isSubscribed": "true",
"lastName": "Linked",
"subscriptionDate": "1551283355"
}
Timeline
With the arrival of Eloqua release 20A (Feb 2020), accountId will be returned at complete depth when retrieving, creating, or updating Contacts using the Application API when the Contact is linked to an Account. Check the Eloqua Release Center for specific dates and times.
Next Steps
If retrieving, creating, or updating Contacts using the Application API, prepare for accountId to be returned at complete depth when the Contact is linked to an Account.
Additional Resources
- View changes for Eloqua's APIs including, new features, significant recent changes, and platform notices, on the Eloqua Developer Changelog.
- If you have questions, post a discussion on Code It!
FAQ
Q: What endpoints are impacted by this change?
A: The following Application API endpoints are impacted:
- 1.0
- Retrieve a contact: GET /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Retrieve a list of contacts: GET /api/REST/1.0/data/contacts
- Default depth is minimal
- Create a contact: POST /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Update a contact: PUT /api/REST/1.0/data/contact/{id}
- Default depth is complete
- Retrieve a contact: GET /api/REST/1.0/data/contact/{id}
- 2.0
- Retrieve contact information: POST /api/REST/2.0/data/contacts
- Default depth is minimal
- Retrieve contact information: POST /api/REST/2.0/data/contacts
Q: When will accountId be returned when creating a Contact using the Application API?
A: accountId will be returned when creating the Contact if the Contact field selected for Account Linkage has a value for an existing Account.
Q: When will accountId be returned when updating a Contact using the Application API?
A: accountId will be returned when updating the Contact:
- If the Contact field selected for Account Linkage is being changed and has a value for an existing Account
- If the Contact field selected for Account Linkage is not being changed, and that Contact is already linked to an Account
Q: Where can I find more information on how a Contact is linked to an Account?
A: Within the Linking accounts to contacts Help Center page.
Q: Why was accountId added?
A: The addition of accountId enables efficiently retrieving additional information on the linked Account.
Q: Is accountId supported with search?
A: Yes, accountId is supported with the search parameter for the Retrieve a list of contacts endpoint. Here is an example to return only Contacts that are linked to an Account:
GET /api/REST/1.0/data/contacts?search=accountId>0