Core API Concepts

Overview

In this article, you’ll find information covering core API concepts such as rate limiting, pagination, authentication, error handling, custom fields, webhooks, and API tokens. For other information about our API, read more in Open APIs Overview.

Rate limiting

To keep the API reliable and fair for everyone, requests are rate-limited per account.

Default limit

30 requests per minute per account, aggregated across all tokens.

Cooldown on limit exceedance

If you exceed the threshold, a 5-minute cooldown is applied to the account, aggregated across all tokens.

During the cooldown period, further requests may be rejected until the cooldown ends.

Endpoint-specific limits (rare)

In rare cases, an endpoint may have a different rate limit than the default. When that happens, the differing limit will be explicitly stated in the API documentation for that endpoint.

Recommended strategies to handle rate limits

Recommended strategies to handle the rate limits include:

• Code optimization

  • Avoid redundant calls (cache results where appropriate).
  • Reduce polling frequency; prefer webhooks/events when available.

• Use bulk operations

  • Prefer batch/bulk endpoints to update or fetch multiple records in one request.
  • Group work into fewer, larger requests instead of many small ones.

• Request queueing

  • Implement a client-side queue with throttling to stay under 30 requests/minute.
  • Add backoff/retry logic when rate-limited, especially during the 5-minute cooldown.
  • Consider prioritizing critical requests and delaying non-urgent ones.

Pagination

Some endpoints (for example, Retrieve Tickets or Retrieve Projects) return results in pages to keep responses fast and predictable.

Query parameters

Use these optional query parameters to control pagination:

• pagesize
  Sets how many items are returned per page.

  • Default: 100
  • Maximum: 500

• page
  Selects which page of results to return.

  • Default: first page (page 1)

Example:

GET /api/tickets?page=2&pageSize=200

Response metadata

Paginated responses include a meta object with pagination details:

• meta.count: total number of items across all pages (not just the current one)
• meta.page: the page number that was returned (the requested page)

Example (shape):

{
  "data": [ /* items */ ],
  "meta": {
    "count": 1247,
    "page": 2
  }
}

Calculating the total number of pages

You can compute how many pages you need to request from:

• the pageSize you sent, and
• the total meta.count returned

So if meta.count = 1247 and pageSize = 200, then:

• totalPages = ceil(1247 / 200) = 7

Common HTTP error codes

✅ 400 Bad Request

Meaning: The request syntax is invalid or required parameters are missing.

🔍 Checklist

• Double-check field names — ensure every input key matches the API schema exactly.
• Check required fields — confirm all mandatory fields are provided (especially IDs).
• Validate data types — ensure strings, numbers, booleans are correctly typed.
• Check nested structure — for JSON payloads, ensure sub-objects are correctly formatted.
• Workato Tip: Use a logger step to print the payload before the HTTP connector or action.
• PlanRadar Tip: When creating or updating a form, verify that required fields like form_id, project_id, and list_ids are present and correctly typed.

✅ 401 Unauthorized

Meaning: Invalid or missing credentials.

🔍 Checklist

• Check API token — confirm the token is active and correct (no whitespace or expired).
• Ensure the Authorization header is correctly formatted (e.g., Authorization: Token xyz).
• Check for environment mismatch — e.g., sandbox token in production recipe.
• Workato Tip: Reconnect the PlanRadar connection under the "Connections" tab to refresh credentials.
• PlanRadar Tip: Verify the user associated with the token has permissions for the action you're performing.

✅ 403 Forbidden

Meaning: You're authenticated but not authorized to perform the action.

🔍 Checklist

• Check role/permissions — ensure the token's user has the right role (e.g., Admin).
• Confirm resource ownership — are you trying to access or modify data outside your user’s scope?
• Make sure the method you're using (e.g., PUT, POST) is allowed on the endpoint.
• Workato Tip: Use an admin-level user for initial testing before using scoped credentials.
• PlanRadar Tip: If modifying list/form/project relationships, verify your token’s access across all affected entities.

✅ 404 Not Found

Meaning: The endpoint or resource doesn't exist.

🔍 Checklist

• Verify the endpoint URL — check API version and path are correct (/api/v1/...).
• Validate IDs — are project_id, form_id, or list_id correct and valid?
• Watch for case sensitivity in names or keys.
• Workato Tip: Log all dynamic IDs used in the API call before making the request.
• PlanRadar Tip: Always call a GET endpoint first to confirm resource existence.

✅ 408 Request Timeout

Meaning: The client took too long to send the request or the server timed out waiting for it.

🔍 Checklist

• Break down large requests into smaller batches.
• Retry with a timeout backoff strategy.
• Workato Tip: Split large looped jobs or reduce data volume per action.
• PlanRadar Tip: Use polling or asynchronous logic for long data syncs.

✅ 409 Conflict

Meaning: The request conflicts with the current state of the resource.

🔍 Checklist

• Check for duplicates — is the object already created?
• Verify unique constraints — e.g., form or field names, list IDs.
• Workato Tip: Add lookup steps before POST to avoid overwriting or collisions.
• PlanRadar Tip: Avoid assigning a list/form multiple times without resetting first.

✅ 410 Gone

Meaning: The resource was intentionally removed and is no longer available.

🔍 Checklist

• Double-check the resource still exists — has it been deleted or archived?
• Verify you’re using an active API version.
• PlanRadar Tip: Some resources may be soft-deleted or locked — confirm in the UI or API.

✅ 415 Unsupported Media Type

Meaning: The request’s Content-Type is not accepted.

🔍 Checklist

• Ensure Content-Type: application/json is set for JSON requests.
• Use correct content type for file uploads (multipart/form-data).
• Workato Tip: Check HTTP connector headers; set manually if needed.

✅ 422 Unprocessable Entity

Meaning: Valid syntax but semantically invalid or missing logic.

🔍 Checklist

• Ensure all list fields are assigned during form-to-project assignments.
• Confirm the assigned lists exist in the same project context.
• Check for required sub-objects or nested structures in the payload.
• Validate content — are date/time formats, enum values, and IDs valid?
• Workato Tip: Use conditional steps to inspect response error messages before retries.
• PlanRadar Tip: If replacing a list in an existing form, remember to create the new list first, then use PATCH or PUT to reassign.

✅ 426 Upgrade Required

Meaning: Server requires protocol upgrade (e.g., HTTP to HTTPS).

🔍 Checklist

• Confirm the endpoint URL uses HTTPS.
• Avoid outdated API tools or deprecated request formats.
• PlanRadar Tip: Always use secure API endpoints; PlanRadar requires HTTPS.

✅ 429 Too Many Requests

Meaning: You’ve hit the API rate limit.

🔍 Checklist

• Inspect response headers for Retry-After, X-RateLimit-Remaining, and X-RateLimit-Reset.
• Use Workato’s Wait or delay step to slow down loops or bulk operations.
• Switch to batch-style operations where possible.
• Implement retry logic with incremental backoff.
• PlanRadar Tip: Be extra cautious when syncing hundreds of users, forms, or tickets in short intervals.

✅ 500 Internal Server Error

Meaning: Unexpected failure on the server side.

🔍 Checklist

• Retry the request after a brief pause — it might be transient.
• Simplify the payload to isolate the cause.
• Check if there's a service status page for outages or reported incidents.
• Workato Tip: Log the raw response body and raise alerts if it persists.
• PlanRadar Tip: Escalate with full request + timestamp if the issue repeats after minimal input.

✅ 502 Bad Gateway

Meaning: An intermediary server received an invalid response from PlanRadar.

🔍 Checklist

• Retry after a short delay.
• Verify PlanRadar isn't experiencing upstream disruptions.
• Workato Tip: Add retry-on-failure handling or circuit breakers for critical actions.

✅ 503 Service Unavailable

Meaning: The API is overloaded or undergoing maintenance.

🔍 Checklist

• Confirm if this aligns with a known maintenance window.
• Use exponential backoff before retries.
• Reduce traffic during peak periods.
• Add health checks or pings before initiating large recipes.
• Workato Tip: Set up Slack/email alerts if repeated 503s are encountered in a run.

✅ 504 Gateway Timeout

Meaning: The upstream service (PlanRadar) didn’t respond in time.

🔍 Checklist

• Break down or parallelize bulk operations to reduce execution time.
• Retry with backoff or schedule during lower-traffic windows.
• Workato Tip: Log timing patterns and monitor execution time trends.

Authentication

General

Our authentication/authorisation takes place via API access token.

An API access token is a piece of data used to authenticate and authorize access to an API (Application Programming Interface). It acts as a key or credential that a client presents to an API to prove its identity and request access to specific resources or services.

Key Concepts

1. Authentication vs. Authorization

• Authentication: Verifies the identity of the client (e.g., who you are).
• Authorization: Determines what resources or actions the client is allowed to access (e.g., what you can do). An API access token is usually used for both purposes: to verify who the client is and what they can access.

2. How an API Access Token Works

• The client (PlanRadar user) first authenticates itself with the API provider/PlanRadar (Log in via username & password into your PlanRadar account).
• After successful authentication (via login), you can create under setting => profil => personal access token your API token.
• This token is must be send with every API request as a way to prove that the client is allowed to access the requested resources.

You can create an API access token in your account then you can only use it to retrieve data from your account with the authorisations assigned to your role

You can switch your user to an account to which you have been invited and create an api access token in this account if you have been given the authorisation to do so when you were invited.
with this API key you can now retrieve all data for which you have authorisations according to your role

Example:

If you are a PlanRadar User who is invited into another account with the rights to access 5 projects and the role to see all tickets there but without the right to create one and you create a API access token in this account you still only have access to get all ticket informations for those 5 projects and not the right to create one.

3. How is an API Access Token used in a request

To authenticate your request, include your API access token in the request headers using the X-PlanRadar-API-Key field.

Example (cURL)

curl -X GET "https://www.planradar.com/api/v1/1234567/projects" \
  -H "Accept: application/json" \
  -H "X-PlanRadar-API-Key: 8473629150cdaf781be3f9a62c4d7e1095ab63f2c8d91e0476b5fa23c9d8e1b7c462f9a031d8c57e4b2f6a9d3c8e7f1204b5d6a7c9e8f103b2d4c6a8e1f3b5c7d902a4e6f8c1b3d5e7f9a2c4b6d8e0f1234567"

Custom fields

What are custom fields?

There are two types of fields available: predefined fields and custom fields.

What’s special about custom fields in the API?

When you fetch ticket data via the API:

• Predefined fields
  Field names are descriptive and consistent across all tickets (for example, subject for the title or status-id for the status).
• Custom fields
  Field names are encoded as IDs and can differ depending on the underlying ticket type (form). They appear under typed-values:

{
  "typed-values": {
    "tf1b533b4b9c4de613": "dummy",
    "tf7fc518e4e0383745": "data"
  }
}

How to map custom field IDs to readable names

To resolve a custom field ID (like tf1b533b4b9c4de613) to its human-readable field name, retrieve the ticket’s ticket type, which provides the mapping of custom fields.

Endpoint to retrieve the ticket type:

GET /api/v1/{customer_id}/ticket_types/{ticket_type_id}

• customer_id
  To find it, check the URL in your browser after signing in to your PlanRadar account. It’s the first number after the top-level domain:
  https://www.planradar.com/dr/1234567/...
• ticket_type_id
  Included as one of the fields in the response body when you fetch ticket data via a ticket endpoint.

The name of the custom field can then be found in the response under

data -> attributes -> typed-fields -> tf1b533b4b9c4de613-> name.

Webhooks

When building integrations with PlanRadar you can use webhooks to react on events happening inside of your PlanRadar account.

After successfully creating the link, every time the specified even takes place, the webhooks will send the information to the URL you’ve provided.

So, in the example above, every time a project is created, the webhooks will be triggered to send data/payload in JSON format to your URL.

A sample payload:

{
  "data": {
    "id": "kbgkpb",
    "type": "projects",
    "attributes": {
      "id": "kbgkpb",
      "name": "Hotep Hotel",
      "parent-id-hashed": "jdkkao",
      "homepage": "",
      "country": "Austria",
      "projectnumber": "PRP01",
      "created-on": "2022-11-30T10:16:36.100Z",
      "updated-on": "2022-11-30T10:16:37.044Z",
      "drstart-date": "2022-11-30T10:16:36.000Z",
      "typed-fields": [],
      "drend-date": "2024-10-30T00:00:00.000Z",
      "description": null,
      "running-number": 15,
      "access-token": null,
      "city": "Vienna",
      "zipcode": null,
      "street": null,
      "status": 1,
      "author-id": "jeqxjq",
      "typed-values": {}
    },
    "relationships": {
      "groups": { "data": [] },
      "project-memberships": {
        "data": [
          {
            "id": "jwazkm",
            "type": "project-memberships"
          }
        ]
      },
      "author": {
        "data": {
          "id": "jeqxjq",
          "type": "users"
        }
      }
    }
  },
  "event_name": "project_created"
}

PlanRadar Specific IDs

When working with PlanRadar API endpoints, you will encounter different types of IDs. These IDs are required to identify customers, projects, tickets, and others when making API requests.

This section explains the most common ID types and where you can find them.

Customer ID

The customer ID identifies your PlanRadar account.

Where to find it

• Log in to the PlanRadar WebApp.

• Look at the URL in your browser.

• The first number in the URL is your customer ID.

Example

https://www.planradar.com/app/1231231/...

In this example, 1231231 is the customer ID.

Project ID

The project ID identifies a specific project within your account.

Where to find it

• Log in to the PlanRadar WebApp.

• Select a project.

• Check the URL in your browser.

• The second number in the URL is the project ID.

Example

https://www.planradar.com/dr/1231231/projects/1456456/...

In this example, 1456456 is the project ID.

Ticket ID

The ticket ID identifies a specific ticket within a project.

Where to find it

• Open a ticket in the PlanRadar WebApp.

• Check the URL in your browser.

• The ticket ID is a combination of letters and numbers, usually separated by hyphens.

Example

https://www.planradar.com/dr/1231231/1456456/defects/c287280d-4108-4278-8657-bb93efe638e6/...

In this example, c287280d-4108-4278-8657-bb93efe638e6 is the ticket ID.

List ID

The list ID identifies a list used within PlanRadar.

Where to find it

• Fetch all available lists through GET /api/v1/{customer_id}/lists/.

• Search the response for the list with the desired name.

• Use the corresponding id value from the API response as the list ID.

Example (snippet response)

{
  "data": [
    {
      "id": "kddmejy",
      "type": "lists",
      "attributes": {
        "id": "kddmejy",
        "name": "Test",

In this example, kddmejy is the list ID of the list with the name Test.

Report Template ID

The report template ID identifies a template used for a ticket report within PlanRadar.

Where to find it

• Fetch all available lists through GET https://www.planradar.com/api/v2/1438698/report_templates.

• Search the response for the template with the desired name.

• Use the corresponding id value from the API response as the report template ID.

Example (snippet response)

{
  "data": [
    {
      "id": "oglpgog",
      "type": "defectradar-report-templates",
      "attributes": {
        "id": "oglpgog",
        "name": "Test"
      },

Filter ID

The filter ID identifies a a saved or predefined filter used to filter for tickets within PlanRadar.

Where to find it

• Fetch all filters of a project through GET /api/v2/{customer_id}/projects/{project_id}/filters.

• Search the response for the filter with the desired name.

• Use the corresponding id value from the API response as the filter ID.

Example (snippet response)

{
  "data": [
    {
      "id": "mdllwno",
      "type": "defectradar-filters",
      "attributes": {
        "id": "mdllwno",
        "name": "Erledigte Tickets",

Ticket Type ID

The ticket type ID identifies the underlying form type of a ticket.

Where to find it

• Fetch all ticket types through GET /api/v1/{customer_id}/ticket_types.

• Search the response for the ticket type with the desired name.

• Use the corresponding id value from the API response as the ticket type ID.

Example (snippet response)

{
  "data": [
    {
      "id": "wddqwzw",
      "type": "ticket-types",
      "attributes": {
        "id": "wddqwzw",
        "created-at": "2025-09-25T13:33:00.436+02:00",
        "updated-at": "2025-10-21T14:13:23.158+02:00",
        "typed-fields": {...
        },
        "name": "Documentation",

Ticket Type ID

The status ID identifies the current status of a ticket.

In the backend, the status is encoded as a two-letter string. To set the status, you can also use the numbers 1 to 6. The mapping is shown below.

Mapping

• 1 or lm => Open
• 2 or ol => In Progress
• 3 or ex => Feedback
• 4 or ma => Resolved
• 5 or ky => Rejected
• 6 or gk => Closed

Where to find it

• Fetch the current status ID of a ticket through /api/v2/{customer_id}/projects/{project_id}/tickets/{uuid}

Example (snippet response)

{
      "id": "jzqdddwx",
      "type": "tickets",
      "attributes": {
        "uuid": "47be734f-4f23-483d-b3ae-591fc3c29fcc",
        ...,
        "status-id": "lm",

Using last_sync_date for incremental syncing

Several endpoints support the last_sync_date query parameter, e.g. Retrieve Lists and Retrieve Tickets. When provided, the endpoint returns only records created after the specified point in time - making it ideal for incremental syncs where you want to avoid re-fetching your entire dataset on every request.

What it expects

last_sync_date accepts a Unix timestamp (seconds elapsed since January 1, 1970 UTC).

Example

To retrieve only lists created after March 1, 2024 at 00:00 UTC (Unix timestamp 1709251200):

GET /api/v1/{customer_id}/lists/?last_sync_date=1709251200

Only lists created after that timestamp will be returned. If the parameter is omitted, all records are returned (subject to pagination limits).

Tips

• Store the timestamp of your last successful sync and pass it on the next request to fetch only new data.
• Combine last_sync_date with pagesize and sort to further control the response.
• Make sure your timestamp is in Unix format (seconds, not milliseconds).
• For long-running syncs, consider pairing this with the page parameter to paginate through results efficiently.