Pre-release — content may change.

Getting Started

Your First Request

Make your first API call and understand JSON:API responses

Now that you've set up authentication, let's make your first API request to the Wicket MDP API.

Prerequisites

  • JWT token generated (see Authentication)
  • Your tenant's API URL: https://tenant-api.wicketcloud.com

Making a Request

Let's fetch a list of people from your Wicket account. This example uses the /people endpoint:

curl -X GET 'https://tenant-api.wicketcloud.com/people?page[size]=5' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/vnd.api+json'
const fetch = require('node-fetch');

const apiUrl = 'https://tenant-api.wicketcloud.com';
const token = 'YOUR_JWT_TOKEN';

async function fetchPeople() {
  const response = await fetch(`${apiUrl}/people?page[size]=5`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/vnd.api+json'
    }
  });

  const data = await response.json();
  console.log(data);
}

fetchPeople();
require 'net/http'
require 'json'

api_url = 'https://tenant-api.wicketcloud.com'
token = 'YOUR_JWT_TOKEN'

uri = URI("#{api_url}/people?page[size]=5")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/vnd.api+json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)
puts data

Understanding the Response

Wicket's API follows the JSON:API specification. Here's what a successful response looks like:

{
  "data": [
    {
      "id": "8f24a446-acac-40bb-8ff3-e6abc051c362",
      "type": "people",
      "attributes": {
        "uuid": "8f24a446-acac-40bb-8ff3-e6abc051c362",
        "given_name": "John",
        "family_name": "Smith",
        "full_name": "John Smith",
        "email": "jsmith@email.ca",
        "job_title": "Front End Developer",
        "created_at": "2017-07-27T22:21:26.824Z",
        "updated_at": "2017-07-27T22:47:45.129Z"
      },
      "relationships": {
        "emails": {
          "data": [
            { "id": "abc123", "type": "emails" }
          ]
        },
        "phones": {
          "data": [
            { "id": "def456", "type": "phones" }
          ]
        }
      }
    }
  ],
  "links": {
    "self": "https://tenant-api.wicketcloud.com/people?page[number]=1&page[size]=5",
    "first": "https://tenant-api.wicketcloud.com/people?page[number]=1&page[size]=5",
    "next": "https://tenant-api.wicketcloud.com/people?page[number]=2&page[size]=5",
    "last": "https://tenant-api.wicketcloud.com/people?page[number]=10&page[size]=5"
  },
  "meta": {
    "total": 47
  }
}

Response Structure

The JSON:API response includes:

  • data: Array of resource objects (or a single object for individual resources)

    • id: Unique identifier (UUID)
    • type: Resource type (e.g., "people", "organizations")
    • attributes: Resource properties (given_name, email, etc.)
    • relationships: Related resources with identifiers
  • links: Pagination and navigation links

    • self: Current request URL
    • first, next, prev, last: Pagination navigation
  • meta: Additional metadata (e.g., total count)

  • included (optional): Full representations of related resources

Fetching a Single Person

You can fetch a specific person by their UUID:

curl -X GET 'https://tenant-api.wicketcloud.com/people/8f24a446-acac-40bb-8ff3-e6abc051c362' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/vnd.api+json'

The response will have a single object in data instead of an array:

{
  "data": {
    "id": "8f24a446-acac-40bb-8ff3-e6abc051c362",
    "type": "people",
    "attributes": { ... }
  }
}

Use the include parameter to fetch related resources in a single request:

curl -X GET 'https://tenant-api.wicketcloud.com/people/8f24a446-acac-40bb-8ff3-e6abc051c362?include=emails,phones,addresses' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/vnd.api+json'

Related resources appear in the included array:

{
  "data": { ... },
  "included": [
    {
      "id": "abc123",
      "type": "emails",
      "attributes": {
        "email_address": "jsmith@email.ca",
        "email_type": "work"
      }
    },
    {
      "id": "def456",
      "type": "phones",
      "attributes": {
        "phone_number": "+1-555-123-4567",
        "phone_type": "mobile"
      }
    }
  ]
}

Common Response Codes

CodeMeaningDescription
200OKSuccessful request
201CreatedResource created successfully
204No ContentSuccessful deletion
400Bad RequestInvalid request format
401UnauthorizedMissing or invalid JWT token
404Not FoundResource doesn't exist
422Unprocessable EntityValidation errors
429Too Many RequestsRate limit exceeded

Error Responses

Errors also follow JSON:API format:

{
  "errors": [
    {
      "status": "404",
      "code": "record_not_found",
      "title": "Record Not Found",
      "detail": "Couldn't find Person with 'id'=invalid-uuid"
    }
  ]
}

Each error object includes:

  • status: HTTP status code
  • code: Machine-readable error code
  • title: Human-readable summary
  • detail: Detailed error message

Parsing Responses

Here's how to extract data from a JSON:API response:

// Fetch people and extract names
const response = await fetch(`${apiUrl}/people?page[size]=5`, {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/vnd.api+json'
  }
});

const json = await response.json();

// Extract person names
const people = json.data.map(person => ({
  id: person.id,
  name: person.attributes.full_name,
  email: person.attributes.email
}));

console.log(people);
// [{ id: '...', name: 'John Smith', email: 'jsmith@email.ca' }, ...]
# Fetch people and extract names
uri = URI("#{api_url}/people?page[size]=5")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{token}"
request['Content-Type'] = 'application/vnd.api+json'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

data = JSON.parse(response.body)

# Extract person names
people = data['data'].map do |person|
  {
    id: person['id'],
    name: person['attributes']['full_name'],
    email: person['attributes']['email']
  }
end

puts people
# [{:id=>"...", :name=>"John Smith", :email=>"jsmith@email.ca"}, ...]

On this page