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.

Properties

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

Retrieve all tags

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

Parameters

Attribute	Description
page number optional	Page number to start from. Page numbering starts at 1, and omitting the `page` parameter will return the first page. e.g. `?page=2`
per_page number optional	Number of records to return per page. The default limit is 25 and the maximum number that can be returned is 100. e.g. `?per_page=20`
sort_by string optional	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 e.g. `?sort_by=created_at`
ids string optional	Comma-separated list of deal tag IDs to be returned in a request. e.g. `?ids=1,2,3`
creator_id number optional	User ID. Returns all tags created by that user. e.g. `?creator_id=1`
name string optional	Name of the tag to search for. This parameter is used in a strict sense. e.g. `?name=publisher`
resource_type string optional	Type name of resource to search for. Possible values: lead contact deal e.g. `?resource_type=lead`

Action

GET /v2/tags

Examples

Retrieve all tags

GET /v2/tags HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/tags", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/tags',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

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

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

Parameters

Attribute	Description
name string required	Must be unique within the scope of the `resource_type`. e.g. `"name": "important"`
resource_type string required	e.g. `"resource_type": "contact"`

Action

POST /v2/tags

Examples

Simple create

POST /v2/tags HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "name": "important",
    "resource_type": "contact"
  },
  "meta": {
    "type": "tag"
  }
}

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"
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
"data": {
  "name": "important",
  "resource_type": "contact"
},
"meta": {
  "type": "tag"
}
}
'
response = RestClient.execute method: :post, url: "https://api.getbase.com/v2/tags", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'name': 'important',
    'resource_type': 'contact'
  },
  'meta': {
    'type': 'tag'
  }
}

response = requests.post(
    url='https://api.getbase.com/v2/tags',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

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

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

Attribute	Description
id number required	Unique identifier of the tag.

Action

GET /v2/tags/:id

Examples

Retrieve a tag with id 5

GET /v2/tags/5 HTTP/1.1

Accept: application/json
Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
response = RestClient.execute method: :get, url: "https://api.getbase.com/v2/tags/5", headers: headers

puts response

import requests
import json

response = requests.get(
    url='https://api.getbase.com/v2/tags/5',
    headers={
      'Accept': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

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

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

Attribute	Description
id number required	Unique identifier of the tag.
name string optional	Must be unique within the scope of the `resource_type`. e.g. `"name": "super important"`
resource_type string optional	e.g. `"resource_type": "contact"`

Action

PUT /v2/tags/:id

Examples

Update a tag with id 5

PUT /v2/tags/5 HTTP/1.1

Accept: application/json
Content-Type: application/json
Authorization: Bearer $ACCESS_TOKEN

{
  "data": {
    "name": "super important"
  }
}

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"
  }
}'

require 'restclient'
headers = {
    "Accept" => "application/json",
    "Content-Type" => "application/json",
    "Authorization" => "Bearer $ACCESS_TOKEN"
}
body = '{
  "data": {
    "name": "super important"
  }
}

'
response = RestClient.execute method: :put, url: "https://api.getbase.com/v2/tags/5", payload: body, headers: headers

puts response

import requests
import json

payload = {
  'data': {
    'name': 'super important'
  }
}

response = requests.put(
    url='https://api.getbase.com/v2/tags/5',
    headers={
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    data=json.dumps(payload),
    verify=True
  )

print(response.text)

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

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

Attribute	Description
id number required	Unique identifier of the tag.

Action

DELETE /v2/tags/:id

Examples

Delete a tag with id 1

DELETE /v2/tags/1 HTTP/1.1

Authorization: Bearer $ACCESS_TOKEN

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

require 'restclient'
response = RestClient.execute method: :delete, url: "https://api.getbase.com/v2/tags/1"

puts response

import requests
import json

response = requests.delete(
    url='https://api.getbase.com/v2/tags/1',
    headers={
      'Authorization': 'Bearer $ACCESS_TOKEN'
    },
    verify=True
  )

print(response.text)

HTTP/1.1 204 No Content

Tags

Properties

Possible values:

Endpoints

Retrieve all tags

Parameters

Possible values:

Possible values:

Create a tag

Parameters

Retrieve a single tag

Parameters

Update a tag

Parameters

Delete a tag

Parameters