Skip to main content

Tagify Public API

Overview​

The Tagify public API allows you to manage users programmatically. It uses API key authentication and follows RESTful conventions. With the API you can:

  • List users
  • Get user details
  • Invite users
  • Activate/deactivate users

API Key management​

Head over to the API section in your company settings to check everything out. Here you can:

  • Enable or disable the API
  • Create new API keys
  • Revoke existing API keys

Base URL​

https://www.tagify.com/api/public/v1

Authentication​

All API requests must include an API key in the Authorization header:

Authorization: Bearer tagify_live_xxxxxxxxxxxxx

Rate Limits​

  • 60 requests per minute per API key
  • 10 requests per minute per IP address (prevents brute force attacks)

Exceeded rate limits return 429 Too Many Requests.

Endpoints​

List Users​

GET /api/public/v1/users

Returns paginated list of users in your company.

Query Parameters:

  • page (integer, default: 0) - Page number
  • limit (integer, default: 50, max: 100) - Results per page
  • status (string) - Filter by status: active, inactive, invited
  • search (string) - Search by name, email, or route_id
  • sort_by (string) - Sort field: name (default) or created_at
  • sort_direction (string) - Sort direction: asc (default) or desc

Response:

{
  "users": [
    {
      "id": "507f1f77bcf86cd799439011",
      "email": "user@example.com",
      "name": "John Doe",
      "active": true,
      "admin": false,
      "invited": false,
      "invitation_accepted_at": "2024-01-15T10:30:00Z",
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-15T10:30:00Z",
      "last_sign_in_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "limit": 50,
    "total": 125,
    "pages": 3
  }
}

Get User​

GET /api/public/v1/users/:id

Returns details for a specific user.

Response:

{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "name": "John Doe",
    "active": true,
    "admin": false,
    "invited": false,
    "invitation_accepted_at": "2024-01-15T10:30:00Z",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "last_sign_in_at": "2024-01-20T14:22:00Z"
  }
}

Invite Users​

POST /api/public/v1/users/invite

Invite one or more users to your company.

Request Body:

{
  "users": [
    {
      "email": "newuser1@example.com",
      "name": "John Doe"
    },
    {
      "email": "newuser2@example.com",
      "name": "Jane Smith"
    },
    {
      "email": "newuser3@example.com"
    }
  ]
}

Note: The name field is optional.

Response:

{
  "invites": {
    "newuser1@example.com": {
      "status": "invited",
      "message": "Invitation sent successfully",
      "user_id": "507f1f77bcf86cd799439012"
    },
    "newuser2@example.com": {
      "status": "already_invited",
      "message": "User is already a member of this company",
      "user_id": "507f1f77bcf86cd799439013"
    }
  }
}

Invite Statuses:

  • invited - New invitation sent
  • already_invited - User already exists in your company
  • already_exists - User exists in another company
  • error - Failed to send invitation

Deactivate User​

PATCH /api/public/v1/users/:id/deactivate

Deactivate a user (prevents login).

Response:

{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "active": false,
    ...
  },
  "message": "User deactivated successfully"
}

Activate User​

PATCH /api/public/v1/users/:id/activate

Reactivate a previously deactivated user.

Response:

{
  "user": {
    "id": "507f1f77bcf86cd799439011",
    "email": "user@example.com",
    "active": true,
    ...
  },
  "message": "User activated successfully"
}

Error Responses​

All errors return JSON with an error field:

{
  "error": "Invalid or revoked API key"
}

Status Codes:

  • 200 OK - Success
  • 201 Created - Resource created successfully
  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Invalid or missing API key
  • 403 Forbidden - Access denied or API disabled
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Example Usage​

cURL​

# List users
curl -H "Authorization: Bearer tagify_live_xxxxxxxxxxxxx" \
  https://www.tagify.com/api/public/v1/users

# Invite users
curl -X POST \
  -H "Authorization: Bearer tagify_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"email":"newuser@example.com","name":"John Doe"}]}' \
  https://www.tagify.com/api/public/v1/users/invite

# Deactivate user
curl -X PATCH \
  -H "Authorization: Bearer tagify_live_xxxxxxxxxxxxx" \
  https://www.tagify.com/api/public/v1/users/507f1f77bcf86cd799439011/deactivate

JavaScript​

const API_KEY = 'tagify_live_xxxxxxxxxxxxx'
const BASE_URL = 'https://www.tagify.com/api/public/v1'

async function listUsers() {
  const response = await fetch(`${BASE_URL}/users`, {
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  })
  return response.json()
}

async function inviteUsers(users) {
  const response = await fetch(`${BASE_URL}/users/invite`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ users }),
  })
  return response.json()
}

// Example usage:
// inviteUsers([
//   { email: 'user1@example.com', name: 'John Doe' },
//   { email: 'user2@example.com', name: 'Jane Smith' }
// ])

async function deactivateUser(userId) {
  const response = await fetch(`${BASE_URL}/users/${userId}/deactivate`, {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${API_KEY}`,
    },
  })
  return response.json()
}