Introduction

Welcome to the Union API Reference pages. Union is a community management tool used by organizations around the world to manage their startup programs and other innovation initiatives.

The platform itself provides a number of functionalities you can read more about on our website. For a percentage of our customers, the SaaS platform is all they need. However, some customers have third party systems in place that they want to synchronize Union data with, and that is why we created our API endpoints. These endpoints allow developers to plug directly into Union data and functionality, and create integrations that are specific to your business cases.

This page guides you in understanding the endpoints available in the Union API, and provides some example code to get you started. The API, as well as this documentation, is a work in progress, and your feedback is quite welcome - you can always reach out to us via help@union.vc.

Let's get started.

Basic Union concepts

To understand how to use the API, it is also important to understand some of the base concepts of Union. There are two key concepts or models we should address before anything else:

Organization - An organization is ground-zero for Union. If you have an account in Union, it is quite likely that it is associated with one or more organizations. The organization holds everything else - all your communities, your billing settings, etc. It is not the most interesting of models, but it certainly is one of the most important. Organizations, most importantly, hold communities, which we'll address right now.
Community - A community is where most of the action happens. Communities are where your members and mentors engage in discussions, organize and attend events, learn from curriculum resources, book rooms, etc. Typically, an organization will have multiple communities around either specific topics ("Acme Blockchain Program") or specific locations ("Acme Boston").

Consequently, most of the requests you will make to the API will require a community id, as most data lives inside the community.

Authentication

To authorize, use this code:

# With shell, you can just pass the correct header with each request
curl -X GET "ApiEndpoint"
  -H "Authorization: YourApiToken"

Make sure to replace YourApiToken with your own API token.

Union uses bearer tokens to authenticate your API requests. Because the API is still being rolled out to customers, get in touch with us if you want to be issued an API token, or if you need to renew your existing credentials.

Union expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: YourApiToken

Organizations

An organization is ground-zero for Union. If you have an account in Union, it is quite likely that it is associated with one or more organizations. The organization holds everything else - all your communities, your billing settings, etc. It is not the most interesting of models, but it certainly is one of the most important.

Get organization details

curl -X GET "https://union.vc/api/v2/organization.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "151de307-0c23-4e2c-bd97-19ce21b338aa",
  "name": "Union",
  "slug": "union",
  "created_at": "2019-08-26T14:55:48.126-04:00",
  "updated_at": "2019-08-26T14:55:48.126-04:00",
  "billing_email": "billing@union.vc"
}

As mentioned before, the Organization holds communities, which then hold discussions, events, feedback, etc. That makes the Organization endpoint relatively simple, as for the most part, you will be interacting with those specific models. However, you may want to query how to get information on the currently authenticated organization. This is how you'd do that.

API Endpoint

GET /api/v2/organization.json

Communities

Communities are the center-piece of Union. They are how you organize around specific topics, locations, or any other criteria, really. With that in mind, there are a number of things you may want to do with communities. This section includes examples of all these actions.

The community object

The community object

{
  "id": "17bb082f-293e-495e-9452-961351fc7d9d",
  "name": "Demo Community",
  "slug": "demo1",
  "custom_attributes": {
    "color_1": "#011993",
    "color_2": "#fffc79"
  },
  "timezone": "America/Los_Angeles",
  "state": "active",
  "description": "An API demo community"
}

Here are the fields that make the community object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a community
`slug`	A human-readable representation of the community name
`name`	The community name
`description`	The description for the community
`timezone`	The community's default timezone, used in event creation and other system functions. A list of available timezones is available below
`state`	The current state of the community. Valid states are `active`, `canceled` and `draft`.
`custom_attributes`	A hash of custom attributes associated with the community.

Community states

Communities can be in one of 3 states, which represent the community life cycle, and use cases like a particular startup program ending. States can be one of:

active - An active community will be accessible as normal, and visible to its members
draft - A community in the draft state can have users, companies and events as normal, but it won't be accessible by users. This is to accomodate the use case where you want to prepare a specific program, and only activate it once all the content is in place.
canceled - A community that has been deactivated, to represent a program or initiative that is over.

Available timezones

Timezone
`Africa/Algiers`	`Africa/Cairo`
`Africa/Casablanca`	`Africa/Harare`
`Africa/Johannesburg`	`Africa/Monrovia`
`Africa/Nairobi`	`America/Argentina/Buenos_Aires`
`America/Bogota`	`America/Caracas`
`America/Chicago`	`America/Chihuahua`
`America/Denver`	`America/Godthab`
`America/Guatemala`	`America/Guyana`
`America/Halifax`	`America/Indiana/Indianapolis`
`America/Juneau`	`America/La_Paz`
`America/Lima`	`America/Lima`
`America/Los_Angeles`	`America/Mazatlan`
`America/Mexico_City`	`America/Mexico_City`
`America/Monterrey`	`America/Montevideo`
`America/New_York`	`America/Phoenix`
`America/Puerto_Rico`	`America/Regina`
`America/Santiago`	`America/Sao_Paulo`
`America/St_Johns`	`America/Tijuana`
`Asia/Almaty`	`Asia/Baghdad`
`Asia/Baku`	`Asia/Bangkok`
`Asia/Bangkok`	`Asia/Chongqing`
`Asia/Colombo`	`Asia/Dhaka`
`Asia/Dhaka`	`Asia/Hong_Kong`
`Asia/Irkutsk`	`Asia/Jakarta`
`Asia/Jerusalem`	`Asia/Kabul`
`Asia/Kamchatka`	`Asia/Karachi`
`Asia/Karachi`	`Asia/Kathmandu`
`Asia/Kolkata`	`Asia/Kolkata`
`Asia/Kolkata`	`Asia/Kolkata`
`Asia/Krasnoyarsk`	`Asia/Kuala_Lumpur`
`Asia/Kuwait`	`Asia/Magadan`
`Asia/Muscat`	`Asia/Muscat`
`Asia/Novosibirsk`	`Asia/Rangoon`
`Asia/Riyadh`	`Asia/Seoul`
`Asia/Shanghai`	`Asia/Singapore`
`Asia/Srednekolymsk`	`Asia/Taipei`
`Asia/Tashkent`	`Asia/Tbilisi`
`Asia/Tehran`	`Asia/Tokyo`
`Asia/Tokyo`	`Asia/Tokyo`
`Asia/Ulaanbaatar`	`Asia/Urumqi`
`Asia/Vladivostok`	`Asia/Yakutsk`
`Asia/Yekaterinburg`	`Asia/Yerevan`
`Atlantic/Azores`	`Atlantic/Cape_Verde`
`Atlantic/South_Georgia`	`Australia/Adelaide`
`Australia/Brisbane`	`Australia/Darwin`
`Australia/Hobart`	`Australia/Melbourne`
`Australia/Melbourne`	`Australia/Perth`
`Australia/Sydney`	`Etc/GMT+12`
`Etc/UTC`	`Europe/Amsterdam`
`Europe/Athens`	`Europe/Belgrade`
`Europe/Berlin`	`Europe/Bratislava`
`Europe/Brussels`	`Europe/Bucharest`
`Europe/Budapest`	`Europe/Copenhagen`
`Europe/Dublin`	`Europe/Helsinki`
`Europe/Istanbul`	`Europe/Kaliningrad`
`Europe/Kiev`	`Europe/Lisbon`
`Europe/Ljubljana`	`Europe/London`
`Europe/London`	`Europe/Madrid`
`Europe/Minsk`	`Europe/Moscow`
`Europe/Moscow`	`Europe/Paris`
`Europe/Prague`	`Europe/Riga`
`Europe/Rome`	`Europe/Samara`
`Europe/Sarajevo`	`Europe/Skopje`
`Europe/Sofia`	`Europe/Stockholm`
`Europe/Tallinn`	`Europe/Vienna`
`Europe/Vilnius`	`Europe/Volgograd`
`Europe/Warsaw`	`Europe/Zagreb`
`Europe/Zurich`	`Europe/Zurich`
`Pacific/Apia`	`Pacific/Auckland`
`Pacific/Auckland`	`Pacific/Chatham`
`Pacific/Fakaofo`	`Pacific/Fiji`
`Pacific/Guadalcanal`	`Pacific/Guam`
`Pacific/Honolulu`	`Pacific/Majuro`
`Pacific/Midway`	`Pacific/Noumea`
`Pacific/Pago_Pago`	`Pacific/Port_Moresby`
`Pacific/Tongatapu`

Listing all the communities in your organization

curl -X GET "https://union.vc/api/v2/communities.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
    {
        "id": "17bb082f-293e-495e-9452-961351fc7d9d",
        "name": "Demo Community",
        "slug": "demo1",
        "custom_attributes": {
            "color_1": "#011993",
            "color_2": "#fffc79"
        },
        "timezone": "America/Los_Angeles",
        "state": "active",
        "description": "An API demo community"
    },
    (...)
}

Returns a list of all the communities in the currently authenticated organization.

API Endpoint

GET /api/v2/communities.json

Getting details on one specific community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "17bb082f-293e-495e-9452-961351fc7d9d",
  "name": "Demo Community",
  "slug": "demo1",
  "custom_attributes": {
    "color_1": "#011993",
    "color_2": "#fffc79"
  },
  "timezone": "America/Los_Angeles",
  "state": "active",
  "description": "An API demo community"
}

Returns a serialized object representing a specific community in the current authenticated organization. Supply the unique community ID that was returned to you when getting the full community list, and the Union API will return the corresponding community information. The same information is returned when creating or updating a community.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>.json

Creating a new community

curl -X POST "https://union.vc/api/v2/communities.json" \
  -H "Authorization: YourApiToken" \
  -F "name=API Creation Test" \
  -F "description=Testing the Union API" \
  -F "timezone=Asia/Tokyo"

The above command returns JSON structured like this:

{
  "id": "b1e41ef3-c661-4399-9bb2-9535e8f7b8da",
  "name": "API Creation Test",
  "slug": "api-creation-test",
  "custom_attributes": {},
  "timezone": "Asia/Tokyo",
  "state": "draft",
  "description": "Testing the Union API"
}

You can create a new community in your organization by submitting a small number of arguments to the communities endpoint. At a bare minimum, communities require only a name and a timezone, but a couple of optional parameters can be passed in. See the list of supported arguments below.

API Endpoint

POST /api/v2/communities.json

Parameters

Parameter	Description	Required
`name`	Name of the community being created	Yes
`description`	A description for the community being created	No
`state`	The state the community should be created in. Can be one of `active` or `draft`. Default is `draft`.	No
`timezone`	The community's default timezone, used in event creation and other system functions. A list of available timezones is available above	Yes

Updating a specific community

curl -X PATCH "https://union.vc/api/v2/communities/<COMMUNITY ID>.json" \
  -H "Authorization: YourApiToken" \
  -F "name=API Editing Test" \
  -F "description=Testing the Union API" \
  -F "timezone=Europe/Lisbon"

The above command returns JSON structured like this:

{
  "id": "b1e41ef3-c661-4399-9bb2-9535e8f7b8da",
  "name": "API Editing Test",
  "slug": "api-creation-test",
  "custom_attributes": {},
  "timezone": "Europe/Lisbon",
  "state": "draft",
  "description": "Testing the Union API"
}

Updating an existing community is as simple as creating one in the first place. All you have to do to update the attributes of a specific community is to make a PATCH request to the endpoint below (note the community id in the URL) with the attributes you want to update.

API Endpoint

PATCH /api/v2/communities/<COMMUNITY ID>.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The ID of the community being updated	Yes
`name`	Name of the community being updated	No
`description`	A description for the community being updated	No
`state`	The state for the community being updated. Can be one of `active` or `draft`. Default is `draft`.	No
`timezone`	The community's default timezone, used in event creation and other system functions. A list of available timezones is available above.	No

Users

Users are, naturally, a critical piece of Union. This section outlines how to manage them via the Union API. One thing that is important to note is that users are always managed through the context of a specific community. That means that the following methods always require a community ID to be passed, as you will see by looking at the listed endpoints.

However, despite the fact that users are managed via the community, user records are canonical (if you want to associate a user with 2 communities, only 1 user record will exist). To guarantee that, when adding users to a community via the API, the system will internally check if the user already exists. If so, no duplicate user is created, and the existing record is simply associated with the second community. This is transparent to you and guaranteed by the business logic.

The user object

The user object

{
  "id": "010ff69f-0a31-4292-b722-de8d0270a8e5",
  "slug": "api-user",
  "profile_url": "https://union.vc/users/api-user",
  "email": "test-user@union.vc",
  "phone_number": null,
  "roles": [],
  "name": "Test User",
  "avatar_url": null,
  "companies": ["Acme"],
  "campuses": [],
  "groups": [],
  "staff_url": "https://union.vc/staff/techstars-paris/users/renaud-visage",
  "created_at": "2018-09-14T14:41:49.224-04:00",
  "updated_at": "2018-09-14T14:41:49.224-04:00"
}

Here are the fields that make the user object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a user
`name`	The user's full name
`slug`	A human-readable representation of the user's name
`profile_url`	The Union profile URL for the user
`email`	The user's email address
`phone_number`	The user's phone number, if known
`roles`	An array of roles associated with the user. Roles can be a combination of `member`, `mentor` and `staff`
`avatar_url`	A URL where an avatar for the user can be retreived
`companies`	An array with the names of companies the user is associated with
`campuses`	An array of the locations in the community that the user is associated with
`groups`	An array with the names of groups the user is associated with
`source`	A text description of how the user joined Union, if available
`staff_url`	The Union staff URL for this particular user
`created_at`	The user record's creation timestamp
`updated_at`	The timestamp for the last time at which the user record was updated

Listing all the users in a community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/users.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "010ff69f-0a31-4292-b722-de8d0270a8e5",
    "slug": "api-user",
    "profile_url": "https://union.vc/users/api-user",
    "email": "test-user@union.vc",
    "phone_number": null,
    "roles": [],
    "name": "Test User",
    "avatar_url": null,
    "companies": ["Acme"],
    "campuses": [],
    "groups": [],
    "source": "Joined through Union",
    "staff_url": "https://union.vc/staff/techstars-paris/users/renaud-visage",
    "created_at": "2018-09-14T14:41:49.224-04:00",
    "updated_at": "2018-09-14T14:41:49.224-04:00"
  },
  (...)
]

Given a community id, this endpoint returns a list of users in that community. The Union API will return 20 results, which can then be paginated with an optional page parameter.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/users.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community for which we're listing users	Yes
`page`	The page of records to retrieve (20 records per page)	No
`updated_since`	Get only profiles that have been updated since this date	No
`role`	Get only profiles that match a specific role. Can be one of `members`, `mentors` or `staff`. If unsubmitted, returns users regardless of role.	No

Getting details on a specific user

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/users/<USER ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "010ff69f-0a31-4292-b722-de8d0270a8e5",
  "slug": "api-user",
  "profile_url": "https://union.vc/users/api-user",
  "email": "test-user@union.vc",
  "phone_number": null,
  "roles": [],
  "name": "Test User",
  "avatar_url": null,
  "companies": ["Acme"],
  "campuses": [],
  "groups": [],
  "source": "Joined through Union",
  "staff_url": "https://union.vc/staff/techstars-paris/users/renaud-visage",
  "created_at": "2018-09-14T14:41:49.224-04:00",
  "updated_at": "2018-09-14T14:41:49.224-04:00"
}

Returns a serialized object representing a user in a given community. Supply a community ID and a user ID, and the Union API will return the corresponding user information.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/users/<USER ID>.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community for which we're listing users	Yes
`USER ID`	The id of the user being retrieved	Yes

Adding a user to a community

curl -X POST \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/users.json" \
  -H "Authorization: YourApiToken" \
  -F "first_name=John" \
  -F "last_name=Doe" \
  -F "email=apitest@union.vc" \
  -F "password=asecurep4ssw0rdtest"

The above command will return a serialized user object (see above)

Adding a user to a community is easy. Given a community id, POST a few basic details about the user, and they will be added to the community. As explained above, if a user record with the submitted email address already exists, that same user record is associated with this community, avoiding duplicates.

Also note that when you create a user, the user object returned from the API will list roles as an empty array. This is because users are created in an onboarding state, and they must complete their registration on the platform to be considered active. At that point, their role will be active too, and further queries to that user will return the role(s) they are assigned and active in.

API Endpoint

POST /api/v2/communities/<COMMUNITY ID>/users.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community that we're adding the user to	Yes
`first_name`	The first name of the user being added	Yes
`last_name`	The last name of the user being added	Yes
`email`	The email of the user being added	Yes
`password`	A password to assign to the user, if creating a new record	Yes

Updating a user record

curl -X PATCH \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/users/<USER ID>.json" \
  -H "Authorization: YourApiToken" \
  -F "first_name=John"

The above command will return a serialized user object (see above)

In order to update an existing user record, send a PATCH request to the endpoint below with the attributes you wish to update.

API Endpoint

PATCH /api/v2/communities/<COMMUNITY ID>/users/<USER ID>.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community the user we're updating belongs to	Yes
`USER ID`	The id of the user we are updating	Yes
`first_name`	The first name of the user being updated	No
`last_name`	The last name of the user being updated	No
`email`	The email of the user being updated	No
`password`	A password to assign to the user	No

Getting a user's activity list

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/users/<USER ID>/activity.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "c20eb83e-9a0c-45ce-996d-2f95973f86db",
    "summary": "John Doe from Acme Corp viewed the perk: Free Hosting",
    "summary_html": "(...)",
    "actor": {
      "name": "John Doe",
      "email": "john.doe@union.vc",
      "profile_url": "https://union.vc/users/john-doe",
      "staff_url": "https://union.vc/staff/union/users/john-doe",
      "company": {
        "name": "Acme Corp",
        "profile_url": "https://union.vc/companies/acme-corp",
        "staff_url": "https://union.vc/staff/union/companies/acme-corp"
      }
    },
    "verb": "viewed",
    "created_at": "2019-12-05T09:38:48.710-05:00",
    "object": {
      "name": "DocSend",
      "url": "http://union.vc/staff/union/perks/f299a21f-46ee-4c14-96c5-8df1e6aec3e8",
      "type": "Perk"
    }
  },(...)
]

It possible to get a list of a user's activities under a specific community by requesting the activity method under the user endpoint. This request will return a paginated serialized activity list for the user.

The activity object

Attribute	Description
`id`	The UUID that uniquely represents an activity item
`summary`	A text-based representation of the activity item
`summary_html`	An HTML-based representation of the activity item
`actor`	A serialized representation of who conducted the activity being represented
`verb`	The verb that represents the activity (e.g. `viewed`, `created`, `commented`, `favorited`, etc)
`object`	A serialized representation of the object being acted upon by the actor
`created_at`	A timestamp for when the activity occurred

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/users/<USER ID>/activity.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community that includes the user being managed	Yes
`USER ID`	The id of the user being managed	Yes
`page`	The page of activity items to fetch	No

Companies

The company object

The company object

{
  "id": "22c82744-b4cf-44a0-9004-f90bc7fea58c",
  "slug": "acme-corp",
  "profile_url": "https://union.vc/companies/acme-corp",
  "name": "Acme Corp",
  "website": null,
  "avatar_url": null,
  "description": null,
  "tagline": null,
  "facebook_url": null,
  "twitter_url": null,
  "linkedin_url": null,
  "angellist_url": null,
  "crunchbase_url": null,
  "instagram_url": null,
  "founders": [],
  "employees": [
    {
      "id": "4d68737e-ee11-42f5-ab85-2b320ca4463c",
      "slug": "john-doe",
      "profile_url": "https://union.vc/users/john-doe",
      "email": "john.doe@acme.org",
      "name": "John Doe"
    }
  ]
}

Here are the fields that make the company object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a company
`slug`	A human-readable representation of the company name
`profile_url`	The user-facing URL for the company's profile in Union
`name`	The company name
`website`	The company's website
`avatar_url`	The URL of the company's most recently uploaded logo, if available
`description`	The company's description
`tagline`	A tagline for the company (e.g. the company motto)
`facebook_url`	The company's Facebook URL
`twitter_url`	The company's Twitter URL
`linkedin_url`	The company's LinkedIn URL
`angellist_url`	The company's AngelList URL
`crunchbase_url`	The company's Crunchbase URL
`instagram_url`	The company's Instagram URL
`founders`	An array of serialized User records representing the company's known founders
`employees`	An array of serialized User records representing the company's known employees

Listing all the companies in a community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "22c82744-b4cf-44a0-9004-f90bc7fea58c",
    "slug": "acme-corp",
    "profile_url": "https://union.vc/companies/acme-corp",
    "name": "Acme Corp",
    "website": null,
    "avatar_url": null,
    "description": null,
    "tagline": null,
    "facebook_url": null,
    "twitter_url": null,
    "linkedin_url": null,
    "angellist_url": null,
    "crunchbase_url": null,
    "instagram_url": null,
    "founders": [],
    "employees": [
      {
        "id": "4d68737e-ee11-42f5-ab85-2b320ca4463c",
        "slug": "john-doe",
        "profile_url": "https://union.vc/users/john-doe",
        "email": "john.doe@acme.org",
        "name": "John Doe"
      }
    ]
  }, (...)
]

Given a community id, this endpoint returns a list of companies in that community. The Union API will return 20 results, which can then be paginated with an optional page parameter.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/companies.json

Parameters

Parameter	Description
`COMMUNITY ID`	The id of the community for which we're listing companies
`page`	The page of records to retrieve (20 records per page)

Getting details on a specific company

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "22c82744-b4cf-44a0-9004-f90bc7fea58c",
  "slug": "acme-corp",
  "profile_url": "https://union.vc/companies/acme-corp",
  "name": "Acme Corp",
  "website": null,
  "avatar_url": null,
  "description": null,
  "tagline": null,
  "facebook_url": null,
  "twitter_url": null,
  "linkedin_url": null,
  "angellist_url": null,
  "crunchbase_url": null,
  "instagram_url": null,
  "founders": [],
  "employees": [
    {
      "id": "4d68737e-ee11-42f5-ab85-2b320ca4463c",
      "slug": "john-doe",
      "profile_url": "https://union.vc/users/john-doe",
      "email": "john.doe@acme.org",
      "name": "John Doe"
    }
  ]
}

Returns a serialized object representing a company in a given community. Supply a community ID and a company ID, and the Union API will return the corresponding company information.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>.json

Adding a company to a community

curl -X POST \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies.json" \
  -H "Authorization: YourApiToken" \
  -F "name=Acme Corp" \
  -F "description=Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin gravida, sem et ornare fringilla, urna nulla accumsan enim, ac venenatis ipsum arcu ut risus. Suspendisse sit amet pulvinar ipsum. Nam accumsan urna vitae condimentum eleifend. Quisque mauris massa, facilisis sed faucibus et, mollis a sapien."

The above command will return the created serialized company object

API Endpoint

POST /api/v2/communities/<COMMUNITY ID>/companies.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community to which we're adding a company	Yes
`name`	The name of the company being added	Yes
`description`	A description for the company being added	No
`website`	The website for the company being added	No
`founded`	The founding date of the company being added	No
`linkedin_url`	The Linkedin profile URL for the company being added	No
`angellist_url`	The AngelList profile URL for the company being added	No
`facebook_url`	The Facebook profile URL for the company being added	No
`twitter_url`	The Twitter profile URL for the company being added	No
`crunchbase_url`	The Crunchbase profile URL for the company being added	No
`instagram_url`	The Instagram profile URL for the company being added	No

Updating a company record

curl -X PATCH \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies.json" \
  -H "Authorization: YourApiToken" \
  -F "name=Edited Acme Corp" \
  -F "description=Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin gravida, sem et ornare fringilla, urna nulla accumsan enim, ac venenatis ipsum arcu ut risus. Suspendisse sit amet pulvinar ipsum. Nam accumsan urna vitae condimentum eleifend. Quisque mauris massa, facilisis sed faucibus et, mollis a sapien."

The above command will return the updated serialized company object

To update a company record, PATCH the attributes you want to change into the endpoint below.

API Endpoint

PATCH /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community that includes the company being managed	Yes
`COMPANY ID`	The id of the company being managed	Yes
`name`	The name of the company being updated	No
`description`	A description for the company being updated	No
`website`	The website for the company being updated	No
`founded`	The founding date of the company being updated	No
`linkedin_url`	The Linkedin profile URL for the company being updated	No
`angellist_url`	The AngelList profile URL for the company being updated	No
`facebook_url`	The Facebook profile URL for the company being updated	No
`twitter_url`	The Twitter profile URL for the company being updated	No
`crunchbase_url`	The Crunchbase profile URL for the company being updated	No
`instagram_url`	The Instagram profile URL for the company being updated	No

Getting a company's activity list

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/activity.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "c20eb83e-9a0c-45ce-996d-2f95973f86db",
    "summary": "John Doe from Acme Corp viewed the perk: Free Hosting",
    "summary_html": "(...)",
    "actor": {
      "name": "John Doe",
      "email": "john.doe@union.vc",
      "profile_url": "https://union.vc/users/john-doe",
      "staff_url": "https://union.vc/staff/union/users/john-doe",
      "company": {
        "name": "Acme Corp",
        "profile_url": "https://union.vc/companies/acme-corp",
        "staff_url": "https://union.vc/staff/union/companies/acme-corp"
      }
    },
    "verb": "viewed",
    "created_at": "2019-12-05T09:38:48.710-05:00",
    "object": {
      "name": "DocSend",
      "url": "http://union.vc/staff/union/perks/f299a21f-46ee-4c14-96c5-8df1e6aec3e8",
      "type": "Perk"
    }
  },(...)
]

You can obtain an activity list for a company, which is a collection of the activities performed by that company's employees under a specific community. This request will return a paginated serialized activity list for the company.

The activity object

Attribute	Description
`id`	The UUID that uniquely represents an activity item
`summary`	A text-based representation of the activity item
`summary_html`	An HTML-based representation of the activity item
`actor`	A serialized representation of who conducted the activity being represented
`verb`	The verb that represents the activity (e.g. `viewed`, `created`, `commented`, `favorited`, etc)
`object`	A serialized representation of the object being acted upon by the actor
`created_at`	A timestamp for when the activity occurred

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/activity.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community that includes the company being managed	Yes
`COMPANY ID`	The id of the company being managed	Yes
`page`	The page of activity items to fetch	No

Relationships

In Union, users are associated with companies via a relationship. The following sections document how to manage a company's list of relationships, thus controlling who is associated with that company, and what roles they might play in that company's organizational chart.

The relationship object

{
  "id": "8735c8c2-3d85-4a15-923d-6ab8e6f510d8",
  "user_id": "2e662ead-4628-4586-be78-4efff054e4b5",
  "role": "founder",
  "job_title": "Sr. Director, Product",
  "full_time": true,
  "since": null,
  "user": {
    "id": "2e662ead-4628-4586-be78-4efff054e4b5",
    "slug": "john-doe",
    "profile_url": "http://union.vc/users/john-doe",
    "email": "jdoe@acme.corp",
    "name": "John Doe"
  }
}

Here are the fields that make the relationship object, as returned via the Union API:

Parameter	Description
`id`	The unique identifier for the relationship between a user and a company
`user_id`	The unique identifier for the user the relationship belongs to
`role`	The user's role within the company. Can be one of `founder` or `employee`
`job_title`	A string representing the user's Job Title at the company
`since`	The date at which the user became associated with the company
`user`	A simplified serialized version of the user object, including `id`, `slug`, `profile_url`, `email` and `name`

Listing the users associated with a company

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships.json"
  -H "Authorization: YourApiToken"

The above command will return JSON structured like this:

[
    {
        "id": "8735c8c2-3d85-4a15-923d-6ab8e6f510d8",
        "role": "founder",
        "job_title": "Sr. Director, Product",
        "full_time": true,
        "since": null,
        "user": {
            "id": "2e662ead-4628-4586-be78-4efff054e4b5",
            "slug": "john-doe",
            "profile_url": "http://union.vc/users/john-doe",
            "email": "jdoe@acme.corp",
            "name": "John Doe"
        }
    }, (...)
]

To get a list of relationships, you can GET from the following endpoint. The result is an array of serialized relationship objects, where each relationship represents an association between a user and the given company.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id for the community that includes the company we're managing	Yes
`COMPANY ID`	The id for the company we're managing	Yes

Getting details on a specific relationship

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "8735c8c2-3d85-4a15-923d-6ab8e6f510d8",
  "role": "founder",
  "job_title": "Sr. Director, Product",
  "full_time": true,
  "since": null,
  "user": {
    "id": "2e662ead-4628-4586-be78-4efff054e4b5",
    "slug": "john-doe",
    "profile_url": "http://union.vc/users/john-doe",
    "email": "jdoe@acme.corp",
    "name": "John Doe"
  }
}

In order to get details on a specific relationship between a user and a company, GET from the following endpoint, by passing IDs for the community, company and relationship.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json

Adding a user to a company

curl -X POST \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships.json" \
  -H "Authorization: YourApiToken" \
  -F "user_id=8735c8c2-3d85-4a15-923d-6ab8e6f510d8" \
  -F "role=founder" \
  -F "job_title=Founder and CEO"

The above command will return the created serialized relationship object

In order to add a user to a specific company, create a relationship between the two by passing the following parameters to the relationships endpoint.

API Endpoint

POST /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id for the community that includes the company we're managing	Yes
`COMPANY ID`	The id for the company we're managing	Yes
`user_id`	The ID for the user being added	Yes
`role`	The role for the user within the company. Can be one of `founder` or `employee`. Defaults to `employee`	No
`job_title`	A string description of the user's job title within the company	No
`since`	The date at which the user joined the company being managed	No

Updating a user's relationship with a company

curl -X PATCH \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json" \
  -H "Authorization: YourApiToken" \
  -F "role=founder" \
  -F "job_title=Founder and CEO"

The above command will return the updated serialized relationship object

In order to update a user's relationship with a company (to change things like a job title, or convert an employee to founder and vice-versa), PATCH to the following endpoint.

API Endpoint

PATCH /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json

Parameter	Description	Required
`COMMUNITY ID`	The id for the community that includes the company we're managing	Yes
`COMPANY ID`	The id for the company we're managing	Yes
`user_id`	The ID for the user being managed	No
`role`	The role for the user within the company. Can be one of `founder` or `employee`. Defaults to `employee`	No
`job_title`	A string description of the user's job title within the company	No
`since`	The date at which the user joined the company being managed	No

Removing a user from a company

curl -X DELETE \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json" \
  -H "Authorization: YourApiToken"

The above command will return the deleted serialized relationship object

In order to remove a user from a company, you destroy the relationship object between the two. You do that by pushing a DELETE request to the following endpoint.

API Endpoint

DELETE /api/v2/communities/<COMMUNITY ID>/companies/<COMPANY ID>/relationships/<RELATIONSHIP ID>.json

Perks

Perks represent specific benefits, normally provided by external entities, to startups participating in programs. An example might be free Amazon Web Services credit, available for limited time. Perks can be managed via the API, and documentation for how to do that is below.

The perk object

The perk object

{
  "id": "d30c6dd4-09d5-4347-a582-9d06d98e8c5a",
  "title": "API Perk test 1",
  "description": "API Perk test description",
  "provider_name": null,
  "provider_id": null,
  "expires_at": null,
  "monetary_value": "19999.0",
  "view_count": 0,
  "favorite_count": 0,
  "published": true
}

Here are the fields that make the perk object, as returned via the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a perk
`title`	The perk's title
`description`	The perk's description, in plain text
`provider_name`	The name for the company that provides the perk, if one exists
`provider_id`	The unique ID for the company that provides the perk, if one exists
`expires_at`	When the perk expires, if present
`monetary_value`	The dollar value associated with the perk
`view_count`	The number of views the perk details page has gotten in Union
`favorite_count`	The number of times the perk has been favorited
`published`	A flag representing whether the perk is published or draft

Listing perks available in a community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/perks.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "d30c6dd4-09d5-4347-a582-9d06d98e8c5a",
    "title": "API Perk test 1",
    "description": "API Perk test description",
    "provider_name": null,
    "provider_id": null,
    "expires_at": null,
    "monetary_value": "19999.0",
    "view_count": 0,
    "favorite_count": 0,
    "published": true,
    "tags": [
      {
        "id": "a300c0df-0d33-4464-9498-38b8899a1d60",
        "name": "Business Model Canvas",
        "slug": "business-model-canvas",
        "parent_id": "1b038bff-f314-4c3f-b47a-82fe1bae8dec",
        "ontology": "topic"
      }
    ]
  },(...)
]

Given a community id, this endpoint returns a list of perks available to that community.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/perks.json

Getting details for a specific perk

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/perks/<PERK ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "d30c6dd4-09d5-4347-a582-9d06d98e8c5a",
  "title": "API Perk test 1",
  "description": "API Perk test description",
  "provider_name": null,
  "provider_id": null,
  "expires_at": null,
  "monetary_value": "19999.0",
  "view_count": 0,
  "favorite_count": 0,
  "published": true,
  "tags": [
    {
      "id": "a300c0df-0d33-4464-9498-38b8899a1d60",
      "name": "Business Model Canvas",
      "slug": "business-model-canvas",
      "parent_id": "1b038bff-f314-4c3f-b47a-82fe1bae8dec",
      "ontology": "topic"
    }
  ]
}

Given a community and a perk id, this endpoing will return a serialized representation of a specific perk, if available to that community.

Adding a perk to a community

curl -X POST \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/perks.json" \
  -H "Authorization: YourApiToken" \
  -F "title=API Perk test" \
  -F "description=Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin gravida, sem et ornare fringilla, urna nulla accumsan enim, ac venenatis ipsum arcu ut risus. Suspendisse sit amet pulvinar ipsum. Nam accumsan urna vitae condimentum eleifend. Quisque mauris massa, facilisis sed faucibus et, mollis a sapien." \
  -F "published=true" \
  -F "monetary_value=19999" \
  -F "tag_slugs=business-model-canvas"

The above command will return the created serialized perk object

In order to add a perk to a community, POST to the following endpoint with the required parameters, and a new perk will be created.

API Endpoint

POST /api/v2/communities/<COMMUNITY ID>/perks.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The ID for the community to which we're adding a perk	Yes
`title`	The perk's title	Yes
`description`	The perk's description, in plain text	Yes
`monetary_value`	The dollar value (as a float) associated with the perk	No
`tag_slugs`	A comma separated list of tags to associate with the perk. See the ontology endpoint for information on which tags are available. At least one tag is required to create a perk.	Yes
`provider_id`	A company ID that represents the company providing the product/services represented by the perk	No
`published`	A boolean that determines whether the perk is published. Defaults to `false`.	No
`expires_at`	The date on which the perk will expire	No

Editing a perk

curl -X PATCH \
  "https://union.vc/api/v2/communities/<COMMUNITY ID>/perks/<PERK ID>.json" \
  -H "Authorization: YourApiToken" \
  -F "description=Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin gravida, sem et ornare fringilla, urna nulla accumsan enim, ac venenatis ipsum arcu ut risus. Suspendisse sit amet pulvinar ipsum. Nam accumsan urna vitae condimentum eleifend. Quisque mauris massa, facilisis sed faucibus et, mollis a sapien." \
  -F "published=false" \
  -F "monetary_value=19999.90" \
  -F "tag_slugs=business-model-canvas"

The above command will return the updated serialized perk object

Given a community id and a perk id, PATCH to this endpoint in order to edit a perk in the given community.

API Endpoint

PATCH /api/v2/communities/<COMMUNITY ID>/perks/<PERK ID>.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The ID for the community where we're updated a perk	Yes
`PERK ID`	The ID for the perk being updated	Yes
`title`	The perk's title	No
`description`	The perk's description, in plain text	No
`monetary_value`	The dollar value (as a float) associated with the perk	No
`tag_slugs`	A comma separated list of tags to associate with the perk. See the ontology endpoint for information on which tags are available.	No
`provider_id`	A company ID that represents the company providing the product/services represented by the perk	No
`published`	A boolean that determines whether the perk is published. Defaults to `false`.	No
`expires_at`	The date on which the perk will expire	No

Removing a perk from a community

curl -X DELETE "https://union.vc/api/v2/communities/<COMMUNITY ID>/perks/<PERK ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "d30c6dd4-09d5-4347-a582-9d06d98e8c5a",
  "title": "API Perk test 1",
  "description": "API Perk test description",
  "provider_name": null,
  "provider_id": null,
  "expires_at": null,
  "monetary_value": "19999.0",
  "view_count": 0,
  "favorite_count": 0,
  "published": true
}

Given a community and a perk id, this endpoing will remove that perk from the community.

API Endpoint

DELETE /api/v2/communities/<COMMUNITY ID>/perks/<PERK ID>.json

Rooms

Read-only endpoint

A big part of running a community in Union is coordinating what happens inside rooms in a physical space (e.g. meeting rooms at accelerator programs around the world). The Rooms endpoint gives you information about the schedule for particular rooms.

The room object

The room object

{
  "id": "496db0da-c852-44f9-b03c-3d4d91628802",
  "name": "Boardroom",
  "location": "Acme Accelerator London Office",
  "community": "Acme Accelerator",
  "cost": 0.0,
  "attribute_list": [
    "Flat screen TV",
    "ChromeCast",
    "Speakers",
    "Omnidirectional microphone"
  ]
}

Here are the fields that make the room object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a room
`name`	The name of the room
`location`	The name of the location (typically a campus) where the room is located
`community`	The name of the community that includes this particular room
`cost`	Dollar amount, used if there is a monetary cost to using this room
`attribute_list`	An array of strings representing some of the room's capabilities

Listing all the rooms in a community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/rooms.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "496db0da-c852-44f9-b03c-3d4d91628802",
    "name": "Boardroom",
    "location": "Acme Accelerator London Office",
    "community": "Acme Accelerator",
    "cost": 0.0,
    "attribute_list": [
      "Flat screen TV",
      "ChromeCast",
      "Speakers",
      "Omnidirectional microphone"
    ]
  }, (...)
]

Given a community id, this endpoint returns a list of rooms in that community.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/rooms.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community for which we're listing rooms	Yes

Getting details and schedule for a specific room

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/rooms/<ROOM ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "496db0da-c852-44f9-b03c-3d4d91628802",
  "name": "Boardroom",
  "location": "Acme Accelerator London Office",
  "community": "Acme Accelerator",
  "cost": 0.0,
  "attribute_list": [
    "Flat screen TV",
    "ChromeCast",
    "Speakers",
    "Omnidirectional microphone"
  ],
  "current_booking": {
    "id": "104428d1-944a-4336-9694-dfc3449908df",
    "title": "Acme Interviews",
    "start_time": "2019-10-11T22:00:00.000-05:00",
    "end_time": "2019-10-12T00:30:00.000-05:00",
    "user": {
      "id": "c518350a-1b36-4c0a-be54-3d4d91628802",
      "slug": "john-doe",
      "profile_url": "http://dev.joinunion.us/users/john-doe",
      "email": "john.doe@union.vc",
      "name": "John Doe",
      "companies": [
        {
          "id": "2751a95b-1bb8-48b4-9b36-5d9b6791dcc0",
          "name": "Union"
        }
      ]
    }
  },
  "future_bookings": [
    (...)
  ]
}

Returns a serialized object representing the room in a given community. Note that it includes a couple of extra details not available when listing all the rooms, like current_booking and future_bookings. These are serialized Room Booking objects, which we detail below:

The room booking object

Attribute	Description
`id`	The unique ID for the room booking
`title`	The title, or purpose of the room booking
`start_time`	The time at which the room booking starts
`end_time`	The time at which the room booking ends
`user`	A serialized user object representing who owns a room booking

Checklists

Work in progressRead-only endpoint

The checklist functionality allows community managers to create checklists that each company in a community should check over time. A checklist will typically include a number of tasks, which can have a title, and optional notes and due dates.

The checklist object

The checklist object

{
  "id": "f932e71f-3a7f-409c-bbc9-2892bbf73d47",
  "name": "Books to read this year",
  "published": true,
  "created_at": "2019-12-08T04:45:51.223-05:00",
  "updated_at": "2019-12-08T04:45:51.223-05:00",
  "tasks": [
    (...)
  ]
}

Here are the fields that make the checklist object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a checklist
`name`	The name of the room
`published`	A flag determining whether the checklist should be shown to end-users
`tasks`	An array of tasks that belong to this checklist

The task object

The task object

{
  "id": "24f93404-6f53-4c58-861e-314b1cad7294",
  "name": "The Checklist Manifesto",
  "notes": "First introduced decades ago by the U.S. Air Force, checklists have enabled pilots to fly aircraft of mind-boggling sophistication. Now innovative checklists are being adopted in hospitals around the world, helping doctors and nurses respond to everything from flu epidemics to avalanches. Even in the immensely complex world of surgery, a simple ninety-second variant has cut the rate of fatalities by more than a third.",
  "due_date": null,
  "position": 1,
  "created_at": "2019-12-08T04:45:51.232-05:00",
  "updated_at": "2019-12-08T04:45:51.232-05:00"
}

Here are the fields that make the checklist object returned by the Union API:

Attribute	Description
`id`	The UUID that uniquely represents a task
`name`	The name of the task
`notes`	An optional description for the task
`due_date`	An optional date before which the task should be completed
`position`	The position of the task in the checklist

Listing all the checklists for a community

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/checklists.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

[
  {
    "id": "f932e71f-3a7f-409c-bbc9-2892bbf73d47",
    "name": "Books to read this year",
    "published": false,
    "created_at": "2019-12-08T04:45:51.223-05:00",
    "updated_at": "2019-12-08T04:45:51.223-05:00",
    "tasks": [
      {
        "id": "24f93404-6f53-4c58-861e-314b1cad7294",
        "name": "The Checklist Manifesto",
        "notes": "First introduced decades ago by the U.S. Air Force, checklists have enabled pilots to fly aircraft of mind-boggling sophistication. Now innovative checklists are being adopted in hospitals around the world, helping doctors and nurses respond to everything from flu epidemics to avalanches. Even in the immensely complex world of surgery, a simple ninety-second variant has cut the rate of fatalities by more than a third.",
        "due_date": null,
        "position": 1,
        "created_at": "2019-12-08T04:45:51.232-05:00",
        "updated_at": "2019-12-08T04:45:51.232-05:00"
      }, (...)
    ]
  }, (...)
]

Given a community id, this endpoint returns a list of checklists in that community.

API Endpoint

GET /api/v2/communities/<COMMUNITY ID>/checklists.json

Parameters

Parameter	Description	Required
`COMMUNITY ID`	The id of the community for which we're listing checklists	Yes

Getting details and schedule for a specific checklist

curl -X GET "https://union.vc/api/v2/communities/<COMMUNITY ID>/checklists/<CHECKLIST ID>.json"
  -H "Authorization: YourApiToken"

The above command returns JSON structured like this:

{
  "id": "f932e71f-3a7f-409c-bbc9-2892bbf73d47",
  "name": "Books to read this year",
  "published": false,
  "created_at": "2019-12-08T04:45:51.223-05:00",
  "updated_at": "2019-12-08T04:45:51.223-05:00",
  "tasks": [
    {
      "id": "24f93404-6f53-4c58-861e-314b1cad7294",
      "name": "The Checklist Manifesto",
      "notes": "First introduced decades ago by the U.S. Air Force, checklists have enabled pilots to fly aircraft of mind-boggling sophistication. Now innovative checklists are being adopted in hospitals around the world, helping doctors and nurses respond to everything from flu epidemics to avalanches. Even in the immensely complex world of surgery, a simple ninety-second variant has cut the rate of fatalities by more than a third.",
      "due_date": null,
      "position": 1,
      "created_at": "2019-12-08T04:45:51.232-05:00",
      "updated_at": "2019-12-08T04:45:51.232-05:00"
    }, (...)
  ]
}

Results a serialized object representing a checklist in a given community.

Ontology

Read-only endpoint

In Union, most entities can be tagged according to our ontology. Tags can represent a variety of things. Here are a few examples:

A perk can be tagged with a specific tag to indicate it is related to that tag (a cloud computing perk, for example)
A person can be tagged as interested in Marketing, and an expert in Blockchain
A company can be tagged as a B2C business working in Advertising

This section documents the Ontology endpoint, which allows you to explore how our ontology is organized, and gives you information on which tags you can use, while managing objects such as the ones described above.

Listing the available ontologies

curl -X GET "https://union.vc/api/v2/ontology.json"
  -H "Authorization: YourApiToken"

The above command will return the following JSON

["topic", "industry", "product_type", "customer_type", "sales_model", "stage"]

A GET request to the ontology endpoint will return an array of the available ontologies in Union. At the time of this writing, these ontologies are as follows:

topic - A list of tags that represent topics an entity might be "interested" in
industry - A list of tags that represent a number of industries an entitity might be associated with
product_type - A list of tags that represent various types of products
customer_type - A list of tags that represent the types of customers a company can have
sales_model - A list of tags that represent the various sales models a company can have
stage - A list of tags that represent the various stages a company can be in

API Endpoint

GET /api/v2/ontology.json

Listing the tags in a specific ontology

curl -X GET "https://union.vc/api/v2/ontology/<ONTOLOGY NAME>.json"
  -H "Authorization: YourApiToken"

The above example will return the following JSON

[
  {
    "id": "61507888-46dd-4bd8-b267-09b7d6f101f5",
    "name": "B2C",
    "slug": "all-about-b2c",
    "parent_id": "1cc15f81-0cf9-467e-a2ca-a37521264b27",
    "ontology": "customer_type"
  },
  {
    "id": "5508ea75-27eb-42d4-b136-506d25405c7c",
    "name": "Men's",
    "slug": "men-s",
    "parent_id": "1cc15f81-0cf9-467e-a2ca-a37521264b27",
    "ontology": "customer_type"
  },
  {
    "id": "2dea4da5-e10c-4d66-98e0-3e093acf55d0",
    "name": "Women's",
    "slug": "women-s",
    "parent_id": "1cc15f81-0cf9-467e-a2ca-a37521264b27",
    "ontology": "customer_type"
  },(...)
]

In order to get the list of tags in a specific ontology, pass an ontology type to the endpoint below.

Note that tags include a parent_id. This is because our ontologies are tree-like structures where some concepts include other concepts (e.g. A "Cryptocurrencies" tag would include "Bitcoin" and "Ethereum"). For the sake of letting you explore the full tree, we include parent_id in the JSON response for this endpoint.

API Endpoint

GET /api/v2/ontology/<ONTOLOGY NAME>.json

Paramters

Parameter	Description
`ONTOLOGY NAME`	The ontology name that we want to list tags for. Can be one of the names returned by the ontology list above (example: `product_type`)

Errors

The Union API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The resources requested is hidden for administrators only.
404	Not Found -- The specified resource could not be found.
429	Too Many Requests -- You're sending too many requests.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.