Connection Helper

The Connection Helper is a helper endpoint to aid in the creation of Connections resources via POST. It provides a quick and easy way to add connections.

When using the Connection Helper, taggings may be added at the same time as well, eliminating the need for multiple POST operations to store that information.

You can also post connections when you use the Person Signup Helper.

The connection helper takes the normal connection format and an optional array of tag data to add to the connection record.

Connections are matched and deduplicated by their API endpoint. If a new connection is created as part of a POST operation, that connection will be added to the campaign associated with your API key and person or entity associated with that endpoint.

Items in the optional tag arrays are matched to existing responses associated with the passed field and section in the campaign matching your API key by name. If a matching response is found, that response will be added to the connection's record. If not, the tag will be ignored unless the action_builder:create_tag field is set to true, in which case a response is created and/or added to the campaign if the field and section match existing fields and sections. Tags can also be removed through the remove_tags array.

Endpoint
Field Names and Descriptions
Links
Related Resources
Scenario: Creating a new connection and adding and removing tags (POST)
Scenario: Updating an existing connection and adding tags (POST)

Endpoints and URL Structures


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

The connection helper lives at the endpoint relating to the collection of people.

Field Names and Descriptions

People Fields

Field Name	Type	Required on POST	Description
connection	Connection*	Yes	A hash representing connection data. You can use any valid fields for connection resources. A `person_id` is required. The ID must be the internal Action Builder ID without the prefix, and the entity connected to must be of a type that forms a valid connection type for the campaign.
add_tags	Taggings*		An array of hashes representing taggings data. You can use any valid fields for tagging resources. Matched fields will add the chosen response to this connection. Invalid fields are ignored. Please refer to the taggings documentation for required fields. Use the `action_builder:create_tag` option to create responses in matching fields if they don't exist already.
remove_tags	Taggings*		An array of hashes representing taggings data. You can use any valid fields for tagging resources. Matched responses will be removed from the connection. Invalid matches are ignored. Please refer to the taggings documentation for required fields.

Related Resources

Scenario: Creating a new connection and adding tags (POST)

If you post with an inline connection hash, we will create or update the matching connection.

This example creates a new connection and adds tags to the connection.

Request

						
POST https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/839db4d7-c86d-4329-a92d-e625134fbb3e/connections		

Header:
OSDI-API-Token: your_api_key_here

{
  "connection": {
    "person_id": "a58866ed-a9a1-493e-a24c-e807e4f890b8"
  },
  "add_tags": [{
    "name": "Engineer",
    "action_builder:section": "Job Info",
    "action_builder:field": "Job Title"
  }]
}

Response

						
{
  "origin_system": "Action Builder",
  "identifiers": [
    "action_builder:09817e37-8757-4346-bddb-9209d00b8aed"
  ],
  "created_date": "2022-02-18T21:13:27.192Z",
  "modified_date": "2022-02-18T21:13:27.192Z",
  "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/839db4d7-c86d-4329-a92d-e625134fbb3e/connections/09817e37-8757-4346-bddb-9209d00b8aed"
    },
    "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/839db4d7-c86d-4329-a92d-e625134fbb3e/connections/09817e37-8757-4346-bddb-9209d00b8aed/taggings"
    },
    "osdi:person": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/a58866ed-a9a1-493e-a24c-e807e4f890b8"
    }
  }
}

Scenario: Updating an existing connection and adding and removing tags (POST)

You can use the connection signup helper to update connections as well. Connections are matched by their Action Builder identifier.

Request

					
POST https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people

Header:
OSDI-API-Token: your_api_key_here

{
  "connection": {
    "person_id": "42d941bd-03e4-486f-99be-b4b49bc0cdb7" 
  },
  "add_tags": [{
    "action_builder:section": "Connection Between People",
    "action_builder:field": "Relation",
    "name": "Friend"
  },
  {
    "action_builder:section": "Connection Between People",
    "action_builder:field": "Relation",
    "name": "Mentor",
    "action_builder:create_tag": true
  }],
  "remove_tags": [{
    "action_builder:section": "Connection Between People",
    "action_builder:field": "Relation",
    "name": "Family Member"
  }]
}

Response

			 	 
200 OK

Content-Type: application/hal+json
Cache-Control: max-age=0, private, must-revalidate					 
					 
{
  "origin_system": "Action Builder",
  "identifiers": [
    "action_builder:e66e3136-34f5-4e13-a2f8-88210d573929"
  ],
  "created_date": "2022-02-18T21:22:43.494Z",
  "modified_date": "2022-02-18T21:22:43.494Z",
  "connection_type": "People + People",
  "person_id": "42d941bd-03e4-486f-99be-b4b49bc0cdb7",
  "inactive": false,
  "_links": {
    "self": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/839db4d7-c86d-4329-a92d-e625134fbb3e/connections/e66e3136-34f5-4e13-a2f8-88210d573929"
    },
    "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/839db4d7-c86d-4329-a92d-e625134fbb3e/connections/e66e3136-34f5-4e13-a2f8-88210d573929/taggings"
    },
    "osdi:person": {
      "href": "https://techworkersunited.actionbuilder.org/api/rest/v1/campaigns/84a684a7-2f5a-4359-bdb4-898ce4fbc88f/people/42d941bd-03e4-486f-99be-b4b49bc0cdb7"
    }
  }
}