Connec!™ proposes the option to store third-party systems IDs it integrates with. This can simplifies the integration with Connec!™ as an external application no longer requires to store the mapping of IDs between the 2 systems.
API operations
When fetching data from the API, the request header CONNEC-EXTERNAL-IDS can be set to ask Connec!™ to return the known external systems IDs
Fetch a collection
GET https://api-connec.maestrano.com/api/v2/cld-1234/people Headers CONNEC-EXTERNAL-IDS: true
Response
{
"people": [
{
"id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "1"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
}
],
"code": "PE1",
"status": "ACTIVE",
"title": "Dr.",
"first_name": "Anastasia",
"last_name": "Brekke",
"job_title": "Chief Directives Engineer",
"birth_date": "1985-01-29T00:00:00Z",
"organization_id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "47"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
"email": {
"address": "dexter@lakin.com"
},
"created_at": "2016-10-04T00:36:23Z",
"updated_at": "2016-10-04T00:36:23Z",
"group_id": "cld-1234",
"channel_id": "org-abcd",
"resource_type": "people"
},
{
"id": [
{
"realm": "org-abcd",
"provider": "connec",
"id": "7ff80260-6bf8-0134-2d54-2f659c5af2a1"
}
],
"code": "PE2",
"status": "ACTIVE",
"title": "Mrs.",
"first_name": "Gretchen",
"last_name": "Kris",
...
}
],
"pagination": {
"skip": 0,
"top": 100,
"total": 2
}
}
Fetch a single resource
To fetch a single resource using a specific external system ID, the parameters opts[provider] and opts[realm] can be specified.
GET https://api-connec.maestrano.com/api/v2/cld-1234/people/1?opts[provider]=my-external-app&opts[realm]=2243 Headers CONNEC-EXTERNAL-IDS: true
Response
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "1"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fef3180-6bf8-0134-2d52-2f659c5af2a1"
}
],
"code": "PE1",
"status": "ACTIVE",
"title": "Dr.",
"first_name": "Anastasia",
"last_name": "Brekke",
"job_title": "Chief Directives Engineer",
"birth_date": "1985-01-29T00:00:00Z",
"organization_id": [
{
"realm": "2243",
"provider": "my-external-app",
"id": "47"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
"email": {
"address": "dexter@lakin.com"
},
"website": {
"url": "http://schaden.com/urban"
},
"created_at": "2016-10-04T00:36:23Z",
"updated_at": "2016-10-04T00:36:23Z",
"resource_type": "people",
"group_id": "cld-1234",
"channel_id": "org-abcd",
}
}
Create or Update a resource
If any of the specified external_ids is matched, the matching resource will be updated. Otherwise a new resource with these external_ids is created
POST https://api-connec.maestrano.com/api/v2/cld-1234/people
Headers
CONNEC-EXTERNAL-IDS: true
Request:
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-application",
"id": "17"
}
],
"title": "Mr.",
"first_name": "Bob",
"last_name": "Builder",
"organization_id": [
{
"realm": "2243",
"provider": "my-application",
"id": "4"
}
]
}
}
Response:
{
"people": {
"id": [
{
"realm": "2243",
"provider": "my-application",
"id": "17"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "8400ddc0-70ab-0134-fc40-74d43510c326"
}
],
"code": "PE136",
"status": "ACTIVE",
"title": "Mr.",
"first_name": "Bob",
"last_name": "Builder",
"organization_id": [
{
"realm": "2243",
"provider": "my-application",
"id": "4"
},
{
"realm": "org-abcd",
"provider": "connec",
"id": "7fe83950-6bf8-0134-2d50-2f659c5af2a1"
}
],
..."created_at": "2016-10-10T00:07:54Z",
"updated_at": "2016-10-10T00:07:54Z",
"group_id": "org-fbba",
"channel_id": "org-fbba",
"resource_type": "people"
}
}