A typical application integration requires to store a mapping your application records IDs with the external application IDs, in this case the Connec!™ IDs.
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.
Scenarios
Your application may already support native integrations with other existing applications outside the Maestrano platform. Supposing one of your customers starts using Maestrano integration services and connects these 2 applications on the Maestrano platform, records may be replicated inside the 2 applications creating duplicates. To avoid this scenario, all the external IDs coming from the applications ecosystems are exposed so records can be merged.
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"
}
}