---
updatedAt: 2025-05-12T20:32:29.000Z
agentTools:
  projectIndex: https://gainfully.readme.io/llms.txt
---

# Retrieve a relationship by id

# OpenAPI definition

````json
{
  "openapi": "3.0.0",
  "info": {
    "title": "Gainfully API",
    "version": "1.0",
    "description": "# Specifications\nThe Gainfully API provides programmatic access to the data in our system. For example a `Relationships` endpoint to retrieve a list of members in your organization or `Events` endpoints to fetch shared content.\n## Authentication\nTo access Gainfully API, a API key is required in the HTTPS Authorization header.\n```shell\ncurl --location --request GET 'https://api.gainfully.com/v1.0/relationships/' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: API_KEY'\n```\n## Retrieving resources\nThe Gainfully API offers predictable and resource-oriented URLs. A single resource is accessed by a unique identifier of an object `GET /example-resource/:id` while a list of resources is fetched by resource type `GET /example-resource/`.\n### Ordering\nSorting is possible when retrieving resources by using the `ordering` query parameter.\nValid attributes for sorting can be found in the query parameters section of the api. To reverse the sorting order, the attribute name must be preceded by ``-``\n- Example: `GET /v1.0/content?ordering=name` (Resource objects are sorted by name in alphabetical order)\n- Example: `GET /v1.0/content?ordering=-name` (Resource objects are sorted by name in reverse alphabetical order)\n\n### Pagination\nWhen retrieving multiple resource objects, the result is always paginated.\nThe Gainfully API uses the limit and offset pagination model where the limit represents the number of objects retrieved per page, while the offset indicates the starting position of the query in relation to the complete set of unpaginated items.\nPaginated responses provide urls for the next and previous pages where available, as well as a total number of objects. ( See `Multiple resource response` for the response format )\n\nThe pagination parameters are:\n\n- `limit`: Number of objects to retrieve in the response. The default and the maximum is 100.\n- `offset`: Starting position of the query in relation to the complete set of unpaginated items.\n\n### Filtering\n\nResources support filtering by certain attributes ( documented for each resource ), which allow for easier fetching of desired resources, and filters are given in the URL as query parameters.\nFilter parameter names are formed by prefixing `filter__` to the field name\n- Example: `GET /v1.0/relationships?filter__type=4`\nCertain filters allow for operators through the `__` symbol. For example, timestamps can allow for relational operators.\n- Example: `GET /v1.0/content?filter__created_at__gte=1572274684`\n\n| Operator  | Description           |\n|-----------|-----------------------|\n| gt        | greater than         |\n| gte       | greater than or equal to |\n| lt        | less than           |\n| lte       | less than or equal to |\n\n\n### Sparse fieldsets\n\nWhen retrieving resource objects, it is possible to request only specific fields by using the `fields` parameter. This parameter takes a value of comma separated field names. Nested attributes can be specified using the dot `.`, for example, `sender.id`.\n- Example: `GET /v1.0/content?fields=name,message`\n\n## Document Structure\n\n### Single resource response\nRetrieving a resource by a specific `id` will yield a single resource object.\nThe top level document contains all attributes of the resource object. This includes the `id` attribute that uniquely identifies the object, unless stated otherwise.\n\n### Multiple resource response\nRetrieving multiple resources yields a paginated list of resource objects.\nThe top level of the document contains the following attributes:\n- `count`: Total number of resources\n- `next`: URL for the next page of resources ( if available )\n- `previous`: URL for the previous page of resources ( if available )\n- `results`: List of resource objects. The resource objects inside the list follow the same structure from the `Single resource response` section.\n\n## Error response\nErrors have a specific document structure which are accompanied by an appropriate HTTP code to allow for easier error handling.\nResources have their specific error codes documented inside their documentation pages.\nAn error response contains the following attributes:\n- `field`: Attribute name inside the body of a request which caused the error\n- `error_code`: String based code for the error\n- `detail`: Description of the error\n\nExample\n\n    {\n        \"field\": \"name\",\n        \"error_code\": \"required\",\n        \"detail\": \"This field is required.\"\n    }\n\n\n## Rate limiting\nThe rate limiting of the API is done on a per-token basis. When the rate limit is reached, the following response is returned:\n\n    Status: 429 Too Many Requests\n    {\n        \"field\": null,\n        \"error_code\": \"throttled\",\n        \"detail\": \"Request was throttled. Expected available in x seconds.\"\n    }\n",
    "termsOfService": "https://www.gainfully.com/terms",
    "contact": {
      "url": "https://www.gainfully.com"
    }
  },
  "servers": [
    {
      "url": "https://api.gainfully.com/v1.0"
    }
  ],
  "paths": {
    "/relationships/{id}": {
      "summary": "To retrieve or delete a relationship by id",
      "get": {
        "tags": [
          "Relationships"
        ],
        "parameters": [
          {
            "name": "id",
            "description": "id of the relationship",
            "schema": {
              "type": "string"
            },
            "in": "path",
            "required": true
          },
          {
            "name": "enable_custom_attrs",
            "description": "To include custom attributes of the user when retrieving relationship.",
            "schema": {
              "type": "boolean"
            },
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Relationship"
                },
                "examples": {
                  "Retrieve relationship by id": {
                    "value": {
                      "id": 2,
                      "status": 0,
                      "sharing_status": 1,
                      "type": 2,
                      "created_at": 1402444800,
                      "updated_at": 1574861716,
                      "user": {
                        "id": 2045,
                        "first_name": "John",
                        "last_name": "Smith",
                        "display_name": "John Smith, CFP",
                        "email": "john@jsmith.com",
                        "licenses": [
                          {
                            "id": 29,
                            "source": 0,
                            "license_id": "1234"
                          },
                          {
                            "id": 29,
                            "source": 1,
                            "license_id": "56789"
                          }
                        ]
                      }
                    }
                  }
                }
              }
            },
            "description": "OK"
          },
          "404": {
            "$ref": "#/components/responses/404_not_found"
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ],
        "operationId": "Retrieve relationship by id",
        "summary": "Retrieve a relationship by id",
        "description": ""
      },
      "parameters": [
        {
          "name": "id",
          "schema": {
            "type": "integer"
          },
          "in": "path",
          "required": true
        }
      ]
    }
  },
  "components": {
    "schemas": {
      "License": {
        "description": "License records of a user.",
        "required": [
          "id",
          "license_id",
          "source"
        ],
        "type": "object",
        "properties": {
          "id": {
            "format": "int32",
            "description": "Unique id of the license record",
            "type": "integer"
          },
          "source": {
            "description": "Source of the license information\nPossible values: 0 - FINRA BrokerCheck, 1 - NIPR Producer Database (PDB)",
            "type": "integer"
          },
          "license_id": {
            "description": "License identifier in the source (i.e. individual CRD in BrokerCheck, NPN in Producer Database)",
            "type": "string"
          }
        },
        "example": {
          "id": 29,
          "source": 0,
          "license_id": "1234"
        }
      },
      "UserWithLicenses": {
        "description": "User of the gainfully app",
        "type": "object",
        "allOf": [
          {
            "required": [
              "licenses"
            ],
            "type": "object",
            "properties": {
              "licenses": {
                "description": "",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/License"
                }
              }
            }
          },
          {
            "$ref": "#/components/schemas/User"
          }
        ],
        "example": {
          "id": 2045,
          "first_name": "John",
          "last_name": "Smith",
          "display_name": "John Smith, CFP",
          "email": "john@jsmith.com",
          "licenses": [
            {
              "id": 29,
              "source": 0,
              "license_id": "1234"
            },
            {
              "id": 29,
              "source": 1,
              "license_id": "56789"
            }
          ]
        }
      },
      "Relationship": {
        "required": [
          "id",
          "user",
          "sharing_status",
          "status",
          "created_at",
          "type",
          "updated_at"
        ],
        "type": "object",
        "properties": {
          "id": {
            "format": "int32",
            "description": "Unique id of the relationship",
            "type": "integer"
          },
          "status": {
            "description": "Possible values: 0 - Active, 1 - Imported, 2 - Pending, 3 - Invited, 4 - Denied",
            "type": "integer"
          },
          "type": {
            "description": "Possible values: 0 - Active, 1 - Admin, 2 - Owner, 4 - Member",
            "type": "integer"
          },
          "sharing_status": {
            "description": "Possible values: 0 - Pending, 1 - Approved, 2 - Denied",
            "type": "integer"
          },
          "created_at": {
            "format": "int32",
            "description": "Timestamp when the relationship was created",
            "type": "integer"
          },
          "updated_at": {
            "format": "int32",
            "description": "Timestamp when the relationship was last updated",
            "type": "integer"
          },
          "user": {
            "$ref": "#/components/schemas/UserWithLicenses",
            "description": "User associated with the organization"
          }
        },
        "example": {
          "id": 2,
          "status": 0,
          "sharing_status": 1,
          "type": 2,
          "created_at": 1402444800,
          "updated_at": 1574861716,
          "user": {
            "id": 2045,
            "first_name": "John",
            "last_name": "Smith",
            "display_name": "John Smith, CFP",
            "email": "john@jsmith.com",
            "licenses": [
              {
                "id": 29,
                "source": 0,
                "license_id": "1234"
              },
              {
                "id": 29,
                "source": 1,
                "license_id": "56789"
              }
            ]
          }
        }
      },
      "User": {
        "description": "User of the gainfully app",
        "required": [
          "id",
          "email",
          "display_name",
          "first_name",
          "last_name"
        ],
        "type": "object",
        "properties": {
          "id": {
            "format": "int32",
            "description": "Unique id of the user",
            "type": "integer"
          },
          "display_name": {
            "nullable": true,
            "description": "Name used for displaying purposes inside the gainfully app",
            "type": "string"
          },
          "first_name": {
            "nullable": true,
            "description": "First name of the user",
            "type": "string"
          },
          "last_name": {
            "nullable": true,
            "description": "Last name of the user",
            "type": "string"
          },
          "email": {
            "description": "Primary email of the user. This is the email that is used in campaigns and various emails sent by the gainfully app.",
            "type": "string"
          }
        },
        "example": {
          "id": 2045,
          "first_name": "John",
          "last_name": "Smith",
          "display_name": "John Smith, CFP",
          "email": "john@jsmith.com"
        }
      },
      "Response404": {
        "title": "Root Type for Response404",
        "description": "",
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "error_code": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          }
        },
        "example": {
          "error_code": "not_found",
          "detail": "Not found."
        }
      }
    },
    "responses": {
      "404_not_found": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Response404"
            },
            "examples": {
              "Example404": {
                "value": {
                  "field": null,
                  "error_code": "not_found",
                  "detail": "Not found."
                }
              }
            }
          }
        },
        "description": ""
      }
    },
    "securitySchemes": {
      "ApiKey": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
      }
    }
  },
  "tags": [
    {
      "name": "Relationships"
    }
  ],
  "x-tagGroups": [
    {
      "name": "Resources",
      "tags": [
        "Relationships",
        "Cards",
        "Events",
        "Campaigns",
        "Templates"
      ]
    }
  ],
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  }
}
````