Tags

The Tags API provides a simple interface to manage tags. The API allows you to create, delete and update your tags. You can retrieve a single tag, a list of all tags, and search for tags.

JSON format

Name	Read Only	Type	Description
id	true	number	Unique identifier of the tag.
creator_id	true	number	User ID of the tag's creator.
name	false	string	Name of the tag.
resource_type	false	string	Type name of the resource the tag is attached to. Possible values: lead, contact, deal
created_at	true	string	Date and time of creation in UTC (ISO8601 format).
updated_at	true	string	Date and time of the last update in UTC (ISO8601 format).

Retrieve all tags

GET /v2/tags

Returns all tags available to the user, according to the parameters provided.

Parameters

Name	Required	Type	In	Description
page	false	number	Query	Page number to start from. Page numbering starts at 1, and omitting the page parameter will return the first page.
per_page	false	number	Query	Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100.
sort_by	false	string	Query	A field to sort by. The default order is ascending. If you want to change the sort order to descending, append :desc to the field e.g. sort_by=name:desc. Possible values: name, updated_at, created_at
ids	false	string	Query	Comma-separated list of deal tag IDs to be returned in a request.
creator_id	false	number	Query	User ID. Returns all tags created by that user.
name	false	string	Query	Name of the tag to search for. This parameter is used in a strict sense.
resource_type	false	string	Query	Type name of resource to search for. Possible values: lead, contact, deal

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/tags \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "items": [
    {
      "data": {
        "id": 1,
        "creator_id": 1,
        "name": "publisher",
        "resource_type": "contact",
        "created_at": "2014-08-27T16:32:56Z",
        "updated_at": "2014-08-27T16:32:56Z"
      },
      "meta": {
        "type": "tag"
      }
    },
    {
      "data": {
        "id": 2,
        "creator_id": 1,
        "name": "marketer",
        "resource_type": "contact",
        "created_at": "2014-08-27T16:32:57Z",
        "updated_at": "2014-08-27T16:32:57Z"
      },
      "meta": {
        "type": "tag"
      }
    },
    {
      "data": {
        "id": 3,
        "creator_id": 1,
        "name": "vendor",
        "resource_type": "contact",
        "created_at": "2014-08-27T16:32:58Z",
        "updated_at": "2014-08-27T16:32:58Z"
      },
      "meta": {
        "type": "tag"
      }
    },
    {
      "data": {
        "id": 4,
        "creator_id": 1,
        "name": "retailer",
        "resource_type": "contact",
        "created_at": "2014-08-27T16:32:59Z",
        "updated_at": "2014-08-27T16:32:59Z"
      },
      "meta": {
        "type": "tag"
      }
    }
  ],
  "meta": {
    "type": "collection",
    "count": 4,
    "links": {
      "self": "http://api.getbase.com/v2/tags.json"
    }
  }
}

---

Create a tag

POST /v2/tags

Creates a new tag. Notice the tag's name must be unique within the scope of the resource_type.

Parameters

Name	Required	Type	In	Description
name	true	string	Body	Must be unique within the scope of the resource_type.
resource_type	true	string	Body	e.g. "resource_type": "contact"

Allowed for

• Agents

Using cURL

curl -v -X POST https://api.getbase.com/v2/tags \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "name": "important",
    "resource_type": "contact"
  },
  "meta": {
    "type": "tag"
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 5,
    "creator_id": 1,
    "name": "important",
    "resource_type": "contact",
    "created_at": "2014-08-27T16:33:00Z",
    "updated_at": "2014-08-27T16:33:00Z"
  },
  "meta": {
    "type": "tag"
  }
}

---

Retrieve a single tag

GET /v2/tags/:id

Returns a single tag available to the user according to the unique ID provided. If the specified tag does not exist, this query will return an error.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the tag.

Allowed for

• Agents

Using cURL

curl -v -X GET https://api.getbase.com/v2/tags/5 \
-H "Accept: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 5,
    "creator_id": 1,
    "name": "important",
    "resource_type": "contact",
    "created_at": "2014-08-27T16:33:00Z",
    "updated_at": "2014-08-27T16:33:00Z"
  },
  "meta": {
    "type": "tag"
  }
}

---

Update a tag

PUT /v2/tags/:id

Updates a tag's information. If the specified tag does not exist, this query will return an error.

Notice if you want to update a tag, you must make sure the tag's name is unique within the scope of the specified resource.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the tag.
name	false	string	Body	Must be unique within the scope of the resource_type.
resource_type	false	string	Body	e.g. contact

Allowed for

• Agents

Using cURL

curl -v -X PUT https://api.getbase.com/v2/tags/5 \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-d '{
  "data": {
    "name": "super important"
  }
}'

Example response

HTTP/1.1 200 OK

Content-Type: application/json; charset=utf-8
Content-Language: en

{
  "data": {
    "id": 5,
    "creator_id": 1,
    "name": "super important",
    "resource_type": "contact",
    "created_at": "2014-08-27T16:33:00Z",
    "updated_at": "2014-08-27T16:33:01Z"
  },
  "meta": {
    "type": "tag"
  }
}

---

Delete a tag

DELETE /v2/tags/:id

Deletes an existing tag. If the specified tag is assigned to any resource, we will remove this tag from all such resources. If the specified tag does not exist, this query will return an error. This operation cannot be undone.

Parameters

Name	Required	Type	In	Description
id	true	number	Query	Unique identifier of the tag.

Allowed for

• Agents

Using cURL

curl -v -X DELETE https://api.getbase.com/v2/tags/1 \
-H "Authorization: Bearer $ACCESS_TOKEN"

Example response

HTTP/1.1 204 No Content