GET Relationships

Retrieve a list of up to 50 relationships. Each relationship includes associated objects, such as organizations, supplier, internal manager, and external manager.

Endpoint

Endpoint

/api/relationships

Method

GET

Headers

Header

Argument

Authorization

Bearer token

Accept

application/json or application/xml

Parameters

Table 1. Query parameters

Parameter

Data Type

Description

limit

 int

Maximum number of items in the response. Maximum: 50.

offset

 int

Number of items to skip from the start. Default: 0.
order_by string Column to order by. Only available for createdAt and modifiedAt elements.
dir string Direction of sorting Available options: Asc, Desc. Default: Asc. Only available for createdAt and modifiedAt elements.
entityId guid Unique identifier of relationship. You can filter by this parameter using these operators: [eq]
name string Relationship name. You can filter by this parameter using these operators: [eq], [contains]
status string Relationship status. You can filter by this parameter using these operators: [eq], [contains]
createdAt datetime Relationship creation timestamp in the following format: YYYY-MM-DDTHH:MM:SS.FFZ. You can filter by this parameter using these operators: [eq], [lt], [gt]
modifiedAt datetime Last updated timestamp in the following format: YYYY-MM-DDTHH:MM:SS.FFZ. You can filter by this parameter using these operators: [eq], [lt], [gt]
relationshipNumber string Relationship number. You can filter by this parameter using these operators: [eq], [contains]
startEffectiveDate datetime Start effective date in the following format: YYYY-MM-DDTHH:MM:SS.FFZ. You can filter by this parameter using these operators: [eq], [lt], [gt]
classification string Classification. You can filter by this parameter using these operators: [eq], [contains]
category string Category. You can filter by this parameter using these operators: [eq], [contains]
residualRisk decimal Residual risk. You can filter by this parameter using these operators: [eq]
inherentRisk decimal Inherent Risk. You can filter by this parameter using these operators: [eq]
includeDeleted boolean Specify whether to include the deleted relationships in the returned list of relationships. Default: False.

Elements

The following elements are available for the Relationships API:

Element

Data Type

Available Options

Description

success

boolean

Whether the request was successful.

totalCount

integer

Total number of relationships that match the filter criteria across all pages.

Note:

Use the limit and offset query parameters to retrieve additional sets of data if totalCount exceeds the page size.

result

array

Current page of relationship results, with up to 50 relationships per request (determined by limit and offset).

errors

array

List of error objects. Typically empty when the request is successful.

entityId

string

Unique, permanent GUID that represents the relationship within the system.

name

string

Name of the relationship, provided by the user during the creation process.

status

string

Relationship_Active

Relationship_Expired

Relationship_Inactive

Current state of the relationship.

relationshipNumber

number

Relationship number, which is generated automatically by the system.

startEffectiveDate

string

Start date of the contract period of performance.

createdAt

datetime

Date and time the relationship was created.

modifiedAt

datetime

Date and time the relationship was last modified.

classification

string

Classification value provided from list of configurable values.

category

string

Services classification for the relationship.

residualRisk

decimal

Residual risk.

inherentRisk

decimal

Inherent risk.
supplier Suppliers List of suppliers belonging to the tenant.
engagement Engagement Engagement object linked to the relationship.
parent relationship Parent relationship Parent relationship object linked to the relationship.
organizations Array of Organizations objects Organization object linked to the relationship.
internal manager Internal manager Internal manager object linked to the relationship.
external manager External manager External manager object linked to the relationship.

Get relationships

Endpoint

GET /api/relationships

Example cURL request
curl --location 'https://<your-instance>.    risk.coupadev.com/api/relationships' \--header 'Accept: application/json' \--header 'Content-Type: application/json' \--header 'Authorization: ••••••'
Example response
{
    "result": {
        "totalCount": 2,
        "relationships": [
            {
                "entityId": "e14e044e-e847-47e4-a8e8-01f2e6341fbf",
                "name": "Relationship_Rest<API&Test2",
                "status": "Relationship_Active",
                "createdAt": "2025-07-28T11:50:16.213Z",
                "modifiedAt": "2025-07-28T11:50:16.213Z",
                "relationshipNumber": "R10071",
                "startEffectiveDate": "2025-07-28T04:00:00Z",
                "classification": "Commodity",
                "category": "Finance and Accounting",
                "residualRisk": 0.0,
                "inherentRisk": 0.0,
                "organizations": [
                    {
                        "entityId": "7fcd72e3-6572-4a44-88c7-9a0fb2cd0661",
                        "name": "3pm",
                        "links": null
                    }
                ],
                "supplier": {
                    "entityId": "dfe010f7-55e3-4577-abad-cd9f8105dc25",
                    "name": "HarshSupplier",
                    "links": [
                        {
                            "href": "api/suppliers",
                            "rel": "retrieve-suppliers",
                            "method": "GET"
                        }
                    ]
                },
                "engagement": null,
                "parentRelationship": null,
                "internalManager": {
                    "entityId": "8b3cbfb3-f345-42ec-a437-0201ccb7769f",
                    "name": "Administrator, Risk Assess",
                    "links": null
                },
                "externalManager": {
                    "entityId": "474cb696-2283-4078-984b-11e13becf89c",
                    "name": "L, HarshSupplierManager",
                    "links": null
                }
            },
            {
                "entityId": "7f563cb3-162c-4145-a2ec-030134c8e4ba",
                "name": "AdminApNewRelWid1",
                "status": "Relationship_Active",
                "createdAt": "2025-02-10T13:14:24.327Z",
                "modifiedAt": "2025-06-27T06:32:13.8Z",
                "relationshipNumber": "R10020",
                "startEffectiveDate": "2025-02-10T05:00:00Z",
                "classification": "Class1",
                "category": "cat1",
                "residualRisk": 0.0,
                "inherentRisk": 0.0,
                "organizations": [
                    {
                        "entityId": "bdf4fc3b-2ec4-4b1e-9fca-e71812036804",
                        "name": "testorg1",
                        "links": null
                    },
                    {
                        "entityId": "99ff3f27-fe10-4077-b2c9-b4c76055a319",
                        "name": "DotnetOrg",
                        "links": null
                    },
                    {
                        "entityId": "b4f7c860-78c9-4a37-8b00-2b8d36424c72",
                        "name": "testorg2",
                        "links": null
                    }
                ],
                "supplier": {
                    "entityId": "85c3d82b-b2bf-4c57-b6e9-9e0469fe83fd",
                    "name": "IntApJZ132659Sup1",
                    "links": [
                        {
                            "href": "api/suppliers",
                            "rel": "retrieve-suppliers",
                            "method": "GET"
                        }
                    ]
                },
                "engagement": null,
                "parentRelationship": null,
                "internalManager": {
                    "entityId": "8b3cbfb3-f345-42ec-a437-0201ccb7769f",
                    "name": "Administrator, Risk Assess",
                    "links": null
                },
                "externalManager": {
                    "entityId": "a54c316c-f4c9-4647-ad03-690b66859503",
                    "name": "IntApJZ132659Sup1, IntApJZ132659Sup1",
                    "links": null
                }
            },
        ]
    },
    "errors": [],
    "success": true
}

Get relationships and filter by ID

Endpoint

GET /api/relationships?entityid[eq]=e14e044e-e847-47e4-a8e8-01f2e6341fbf

Example cURL request
curl --location --globoff 'https://<your-instance>.risk.coupadev.com/api/relationships?entityid[eq]=e14e044e-e847-47e4-a8e8-01f2e6341fbf' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'
Example response
{
    "result": {
        "totalCount": 1,
        "relationships": [
            {
                "entityId": "e14e044e-e847-47e4-a8e8-01f2e6341fbf",
                "name": "Relationship_Rest<API&Test2",
                "status": "Relationship_Active",
                "createdAt": "2025-07-28T11:50:16.213Z",
                "modifiedAt": "2025-07-28T11:50:16.213Z",
                "relationshipNumber": "R10071",
                "startEffectiveDate": "2025-07-28T04:00:00Z",
                "classification": "Commodity",
                "category": "Finance and Accounting",
                "residualRisk": 0.0,
                "inherentRisk": 0.0,
                "organizations": [
                    {
                        "entityId": "7fcd72e3-6572-4a44-88c7-9a0fb2cd0661",
                        "name": "3pm",
                        "links": null
                    }
                ],
                "supplier": {
                    "entityId": "dfe010f7-55e3-4577-abad-cd9f8105dc25",
                    "name": "HarshSupplier",
                    "links": [
                        {
                            "href": "api/suppliers",
                            "rel": "retrieve-suppliers",
                            "method": "GET"
                        }
                    ]
                },
                "engagement": null,
                "parentRelationship": null,
                "internalManager": {
                    "entityId": "8b3cbfb3-f345-42ec-a437-0201ccb7769f",
                    "name": "Administrator, Risk Assess",
                    "links": null
                },
                "externalManager": {
                    "entityId": "474cb696-2283-4078-984b-11e13becf89c",
                    "name": "L, HarshSupplierManager",
                    "links": null
                }
            }
        ]
    },
    "errors": [],
    "success": true
}

Get relationships and filter by status, created date, and name

Endpoint

GET /api/relationships?status[eq]=Relationship_Active&createdAt[lt]=2024-12-11T06:20:52.03Z&name[contains]=xyz

Example cURL request
curl --location --globoff 'https://    <your-instance>.risk.coupadev.com/api/    relationships?status[eq]    =Relationship_Active&createdAt[lt]    =2024-12-11T06%3A20%3A52.03Z&name    [contains]=xyz' \--header 'Accept: application/json' \--header 'Content-Type: application/json' \--header 'Authorization: ••••••'
Example response
{
    "result": {
        "totalCount": 1,
        "relationships": [
            {
                "entityId": "3b3dbc0e-fb38-46b3-81c0-3a9514324888",
                "name": "xyz_New_engagement",
                "status": "Relationship_Active",
                "createdAt": "2024-12-09T06:39:01.093Z",
                "modifiedAt": "2025-05-26T09:17:30.05Z",
                "relationshipNumber": "R10000",
                "startEffectiveDate": "2024-09-29T18:30:00Z",
                "classification": "1101",
                "category": "1101",
                "residualRisk": 50.00,
                "inherentRisk": 0.0,
                "organizations": [
                    {
                        "entityId": "fa0282c0-4768-406b-8495-f56d7420ecd9",
                        "name": "org1",
                        "links": null
                    }
                ],
                "supplier": {
                    "entityId": "e2c2ae5b-f548-47aa-8613-9afca685d5f5",
                    "name": "Dell",
                    "links": [
                        {
                            "href": "api/suppliers",
                            "rel": "retrieve-suppliers",
                            "method": "GET"
                        }
                    ]
                },
                "engagement": {
                    "entityId": "4584be4e-2a29-4901-9546-7be64f7784e9",
                    "name": "xyz_New_engagement",
                    "links": null
                },
                "parentRelationship": {
                    "entityId": "386baed9-905b-4934-81d1-134b71adac64",
                    "name": "Engagement 003",
                    "links": [
                        {
                            "href": "api/relationships",
                            "rel": "retrieve-relationships",
                            "method": "GET"
                        }
                    ]
                },
                "internalManager": {
                    "entityId": "999f973a-165a-4ee9-a46f-d44b09863504",
                    "name": "Administrator, Risk Assess",
                    "links": null
                },
                "externalManager": {
                    "entityId": "0c8e8fd0-cc10-4fbb-9732-94e14ea160a1",
                    "name": "supplier user, Dell",
                    "links": null
                }
            }
        ]
    },
    "errors": [],
    "success": true
}