Connections

Connections represent a link between two people or entities. They are a way to link entities like people, places or groups together. Connections can exist between entities of the same type or entities of a different type.

Taggings are used to track unique information about each connection.

Endpoints and URL Structures
Field Names and Descriptions
Links
Related Resources
Scenario: Retrieving a Collection of Connections Resources (GET)
Scenario: Retrieving an Individual Connection Resource (GET)
Scenario: Creating a New Connection Resource (POST)
Scenario: Modifying an Individual Connection Resource (PUT)
Scenario: DELETE

Endpoints and URL Structures


https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people/[person_id]/connections

Connection resources live exclusively at the above endpoint. The endpoint returns a collection of all the connections associated with your API key and specified campaign and person.

URL Structures:


https://[your-sub-domain].actionbuilder.org/api/rest/v1/campaigns/[campaign_id]/people/[person_id]/connections/[connection_id]

To address a specific connection, use the resource type name like:


https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0

Field Names and Descriptions

Connection Fields

Field Name	Type	Required on POST	Description
origin_system	string		A human readable string identifying where this connection originated.
identifiers	strings[]		An array containing the read-only Action Builder identifier of this resource in the format `[system name]:[id]`. See the general concepts document for more information about identifiers.
created_date	datetime		The date and time the resource was created. System generated, not editable.
modified_date	datetime		The date and time the resource was last modified. System generated, not editable.
connection_type	string		A human readable explanation of the types of entities that form this connection.
person_id	string	Yes	The Action Builder identifier of the other entity forming this connection.
inactive	boolean		Indicates whether this connection is inactive or not. One of either true or false. Default is false.

Links

Link Name	Description
self	A link to this individual connection resource.
action_builder:campaign	A link to the campaign this connection is in. Click here for campaigns documentation.
action_builder:connection_type	A link to the connection type of this connection. Click here for connection types documentation.
osdi:person	A link to other entity forming this connection. Click here for people documentation.
osdi:taggings	A link to the taggings of this connection. Click here for taggings documentation.

Related Resources

Scenario: Retrieving a collection of connections resources (GET)

Connections resources are sometimes presented as collections of connections. For example, calling the connections endpoint will return a collection of all the connections associated with that API key and specified campaign and person.

Request

						
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections		

Header:
OSDI-API-Token: your_api_key_here

Response

						
{
  "per_page": 25,
  "page": 1,
  "total_pages": 1,
  "_embedded": {
    "action_builder:connections": [
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:da78eb44-b2f6-416e-b841-7a619cebd4fb"
        ],
        "created_date": "2022-02-16T15:58:52.751Z",
        "modified_date": "2022-02-16T15:58:52.751Z",
        "connection_type": "People + Locals",
        "person_id": "a58866ed-a9a1-493e-a24c-e807e4f890b8",
        "inactive": false,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/da78eb44-b2f6-416e-b841-7a619cebd4fb"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "action_builder:connection_type": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/connection_types/4e07f3eb-d0e4-4b5b-8bc4-1368af2e535f"
          },
          "osdi:taggings": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/da78eb44-b2f6-416e-b841-7a619cebd4fb/taggings"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/a58866ed-a9a1-493e-a24c-e807e4f890b8"
          }
        }
      },
      {
        "origin_system": "Action Builder",
        "identifiers": [
          "action_builder:95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
        ],
        "created_date": "2021-12-22T15:03:47.788Z",
        "modified_date": "2021-12-22T15:04:00.343Z",
        "connection_type": "People + People",
        "person_id": "124698f6-3496-4141-a39d-d51a174cc907",
        "inactive": false,
        "_links": {
          "self": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
          },
          "action_builder:campaign": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
          },
          "action_builder:connection_type": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/connection_types/f2cafa3f-213c-47ab-8188-868c75048f5f"
          },
          "osdi:taggings": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0/taggings"
          },
          "osdi:person": {
            "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections"
    },
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_builder",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "action_builder:connections": [
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/da78eb44-b2f6-416e-b841-7a619cebd4fb"
      },
      {
        "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
      }
    ]
  }
}

Scenario: Retrieving an individual connection resource (GET)

Calling an individual connection resource will return the connection directly, along with all associated fields and appropriate links to additional information about the connection.

Request

					
GET https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0

Header:
OSDI-API-Token: your_api_key_here

Response

			 	 
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate					 
					 
{
  "origin_system": "Action Builder",
  "identifiers": [
    "action_builder:95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
  ],
  "created_date": "2021-12-22T15:03:47.788Z",
  "modified_date": "2021-12-22T15:04:00.343Z",
  "connection_type": "People + People",
  "person_id": "124698f6-3496-4141-a39d-d51a174cc907",
  "inactive": false,
  "_links": {
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_builder",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
    },
    "action_builder:campaign": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
    },
    "action_builder:connection_type": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/connection_types/f2cafa3f-213c-47ab-8188-868c75048f5f"
    },
    "osdi:taggings": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0/taggings"
    },
    "osdi:person": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
    }
  }
}

Scenario: Creating a New Connection (POST)

The connections collection does not allow POST -- posting a new connection directly to the connections endpoint is not allowed.

Connections can be created using the connection signup helper, documented here.

Scenario: Modifying an Existing connection (PUT)

You can modify an existing connection by using PUT at its individual endpoint.

In this example, the connection is being changed from active to inactive.

Request

					
PUT https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0

Header:
OSDI-API-Token: your_api_key_here		

{
  "inactive": "true"
}

Response

			 	 
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate					 
					 
{
  "origin_system": "Action Builder",
  "identifiers": [
    "action_builder:95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
  ],
  "created_date": "2021-12-22T15:03:47.788Z",
  "modified_date": "2021-12-22T15:04:00.343Z",
  "connection_type": "People + People",
  "person_id": "124698f6-3496-4141-a39d-d51a174cc907",
  "inactive": true,
  "_links": {
    "curies": [
      {
        "name": "osdi",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      },
      {
        "name": "action_builder",
        "href": "https://actionbuilder.org/docs/v1/{rel}",
        "templated": true
      }
    ],
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0"
    },
    "action_builder:campaign": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f"
    },
    "action_builder:connection_type": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/connection_types/f2cafa3f-213c-47ab-8188-868c75048f5f"
    },
    "osdi:taggings": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/60df91c0-edf5-4eea-b5d7-ec6f699e7e8f/connections/95eee91a-3374-4cb1-b98c-3c6846f8ffb0/taggings"
    },
    "osdi:person": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/124698f6-3496-4141-a39d-d51a174cc907"
    }
  }
}

Scenario: DELETE

Deleting of connections is not allowed. Attempts will result in errors.