--- updatedAt: 2025-05-12T20:32:38.000Z agentTools: projectIndex: https://gainfully.readme.io/llms.txt --- # Retrieve organization connection events # 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": { "/events/?event=organization_relationship": { "summary": "Retrieve organization connection events", "description": "", "get": { "tags": [ "Events" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListResponseRelationshipEvent" }, "examples": { "Retrieve organization relationship events": { "value": { "count": 4, "next": null, "previous": null, "results": [ { "relation_type": 0, "relation_status": 1, "action": "added", "timestamp": 1582208596, "user": { "id": 7, "first_name": "John", "last_name": "Smith", "display_name": "John Smith, CFP", "email": "john@jsmith.com" } }, { "relation_type": 0, "relation_status": 0, "action": "updated", "timestamp": 1582208596, "user": { "id": 7, "first_name": "John", "last_name": "Smith", "display_name": "John Smith, CFP", "email": "john@jsmith.com" } }, { "relation_type": 4, "relation_status": 0, "action": "updated", "timestamp": 1582208596, "user": { "id": 7, "first_name": "John", "last_name": "Smith", "display_name": "John Smith, CFP", "email": "john@jsmith.com" } }, { "relation_type": 4, "relation_status": 0, "action": "removed", "timestamp": 1582208596, "user": { "id": 7, "first_name": "John", "last_name": "Smith", "display_name": "John Smith, CFP", "email": "john@jsmith.com" } } ] } } } } }, "description": "OK" } }, "security": [ { "ApiKey": [] } ], "operationId": "Retrieve organization connection events", "summary": "Retrieve organization connection events" }, "parameters": [ { "name": "event", "description": "Required parameter used to specify what type of events to retrieve", "schema": { "default": "organization_relationship", "type": "string" }, "in": "query", "required": true }, { "name": "filter__timestamp__gt", "description": "Filter events by a minimum timestamp", "schema": { "format": "int32", "type": "integer" }, "in": "query" }, { "name": "filter__timestamp__lt", "description": "Filter events by a maximum timestamp", "schema": { "format": "int32", "type": "integer" }, "in": "query" }, { "name": "relative_xdays", "description": "Used to specify a time period to retrieve events from ( events from the last x number of days, up to 90, starting with the current timestamp )", "schema": { "format": "int32", "type": "integer" }, "in": "query", "required": false }, { "name": "fields", "description": "Specify which fields to retrieve for each event", "schema": { "type": "string" }, "in": "query", "required": false }, { "name": "filter__action", "description": "Filter events by action", "schema": { "enum": [ "added", "removed", "updated" ], "type": "string" }, "in": "query", "required": false }, { "name": "filter__relation_type", "description": "Filter events by relationship type ( 0 - Connection, 1 - Admin, 2 - Owner, 4 - Member )", "schema": { "type": "integer" }, "in": "query", "required": false }, { "name": "filter__relation_status", "description": "Filter by events by relationship status ( 0 - Active, 1 - Imported, 2 - Pending, 3 - Invited, 4 - Denied )", "schema": { "type": "integer" }, "in": "query" }, { "name": "offset", "description": "Starting position of the query in relation to the complete set of unpaginated items.", "schema": { "type": "number" }, "in": "query" }, { "name": "limit", "description": " Number of objects to retrieve in the response. By default, the value is the maximum, which is 100.", "schema": { "type": "integer" }, "in": "query" }, { "examples": { "sort by timestamp in descending order": { "value": "-timestamp" }, "sort by action and timestamp": { "value": "action,timestamp" } }, "name": "ordering", "description": "Sort the results by the specified fields. By default, the results are sorted by ``timestamp``, *i.e.*, the oldest ones come first. To sort the results in the reverse order of a field, the field name must be preceded with the ``-`` sign. To sort the results by multiple fields, the field names must be separated by commas.", "schema": { "enum": [ "relationship_type", "action", "timestamp" ], "type": "string" }, "in": "query" } ] } }, "components": { "schemas": { "ListResponse": { "description": "Response format for list requests", "required": [ "count", "results", "next", "previous" ], "type": "object", "properties": { "next": { "nullable": true, "description": "Automatically generated url for the next page of results", "type": "string" }, "count": { "format": "int32", "description": "Total number of unpaginated results for the request", "type": "integer" }, "previous": { "nullable": true, "description": "Automatically generated url for the previous page of results", "type": "string" }, "results": { "description": "Paginated list of requested objects", "type": "array", "items": {} } }, "example": { "count": 1, "next": null, "previous": null, "results": [] } }, "ListResponseRelationshipEvent": { "description": "", "type": "object", "allOf": [ { "required": [ "results" ], "type": "object", "properties": { "results": { "description": "", "type": "array", "items": { "$ref": "#/components/schemas/RelationshipEvent" } } } }, { "$ref": "#/components/schemas/ListResponse" } ] }, "RelationshipEvent": { "description": "Relationship events represent status updates to the organization's relationships", "required": [ "timestamp", "user", "action", "relation_type", "relation_status" ], "type": "object", "properties": { "timestamp": { "description": "Unix timestamp of the event", "type": "integer" }, "user": { "$ref": "#/components/schemas/User", "description": "User the organization has a relationship with" }, "action": { "description": "Action performed on the relationship", "enum": [ "added", "removed", "updated" ], "type": "string" }, "relation_type": { "description": "Possible values: 0 - connection, 4 - member", "type": "integer" }, "relation_status": { "description": "Possible values: 0 - Active, 1 - Imported, 2 - Pending, 3 - Invited, 4 - Denied", "type": "integer" } }, "example": { "relation_type": 0, "relation_status": 1, "action": "added", "timestamp": 1582208596, "user": { "id": 7, "first_name": "John", "last_name": "Smith", "display_name": "John Smith, CFP", "email": "john@jsmith.com" } } }, "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" } } }, "securitySchemes": { "ApiKey": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Events", "description": "# Notes:\n- This resource does not support retrieving specific events by a unique id.\n- The event api is able to retrieve events up to `90` days, the recent `90` days by default. You can change the default behavior by using the `filter__timestamp__gt`, `filter__timestamp__lt`, and `relative_xdays` query parameters. If you periodically call the api to retrieve the events for analysis, it's recommended that you specify the `filter__timestamp__lt` and `filter__timestamp__gt` query parameters to avoid retrieving the events multiple times.\n\nFilters:\n- The supported filters vary from event type to type. Supported filters will be described for each type of event.\n\nSorting:\n - By default, the retrieved events are sorted in the ascending order of the `timestamp`. Some events support sorting by other fields too, which can be found at the QUERY PARAMETERS section of each type of event. *`WARNING:`* Due to the dynamic nature of events, if you sort the events differently than the default, you may miss some new events or get some events twice when you go from page to page.\n" } ], "x-tagGroups": [ { "name": "Resources", "tags": [ "Relationships", "Cards", "Events", "Campaigns", "Templates" ] } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ````