API
      Back to home
      1. Firefish Software Help Centre
      2. Integrations
      3. API

      API Troubleshooting FAQ

      Answers to some of the most common problems faced when working with the Firefish Public API

      Contents

      Introduction

      The Firefish Public API allows you to connect Firefish with other systems, build custom automations, and integrate data into your own tools. Many recruiters use it to automatically update records, sync candidates and contacts, or power reporting dashboards.

      To get the most out of the API, you’ll need at least a basic understanding of how to make web requests (GET, POST, PUT, DELETE) and how to work with JSON data. Many users get started with tools like Postman or AI assistants (such as ChatGPT or Claude) to help write and test their queries.

      This FAQ is designed to help non-technical users (like recruiters or administrators) troubleshoot common issues when working with the API.

      👉 For the full technical documentation, including all available endpoints and examples, visit our developer site: https://developer.firefishsoftware.com.

      🔍 Why isn’t my search returning all of/any data?

      By default, search endpoints only return data created in the last 7 days if you don’t add date filters. Each search is also limited to 1,000 records per call.


      ✅ Fix: Add from-date and to-date (or use-updated-dates where available). If you need more than 1,000 results, split your searches into smaller date ranges and/or use pagination to retrieve multiple pages of results.

      🔑 Why do I keep getting a “401 Unauthorized” error?

      This means your access token is missing, expired, or doesn’t have the right permissions. Tokens expire after 10 minutes.


      ✅ Fix: Always include the token in the Authorization header, refresh tokens regularly, and check you’ve enabled the right API scopes in Firefish settings (e.g. candidatesAPI-read).

      📝 Why is my request failing with “400 Bad Request”?

      This happens when something is typed wrong, missing, or invalid. Common causes:

      • A misspelled parameter (e.g. candidatesAPI-rea).

      • A date not in ISO-8601 UTC format (e.g. 2023-12-01T14:45:23.000Z).

      • A value isn’t valid for a dropdown field (e.g. status/type).

      • A duplicate where Firefish enforces uniqueness (e.g. email addresses, company names, LinkedIn URLs).


        ✅ Fix: Double-check spelling, use valid dropdown values, and make sure you’re not creating duplicates.

      👥 Why does the same person show up twice — once as a Candidate and once as a Contact?

      In Firefish, a person can exist as both a Candidate (jobseeker) and a Contact (hiring manager). They share the same Ref ID but are separate records.


      ✅ Fix: Decide which record you want to use. Updates to one won’t automatically update the other.

      📄 Why can’t I create a candidate/contact?

      Some fields are mandatory when creating records. For example, when creating a candidate you must include the source field. Recently, this changed — you now need to provide your API Profile name, not the old “registration - public api” value.


      ✅ Fix: Check that all required fields are included before sending.

      📞 Why isn’t my phone number search working?

      Search endpoints return phone numbers exactly as they were entered in Firefish. If recruiters didn’t use international formatting, your system may struggle to match them.

      The Caller ID Lookup endpoint works differently: it expects an E.164 formatted number (e.g. +447912345678) and will match the correct Candidate/Contact regardless of how the number was originally entered.

       

      ✅ Fix:

      • Convert numbers retrieved from search endpoints into E.164 format in your system.

      • Use Caller ID Lookup when searching by phone number — it handles E.164 natively.

      📂 Why won’t my CV or document upload?

      When uploading documents, you must provide:

      1. A valid file type (e.g. CV, InterviewNotes, Other).

      2. A filename.
        If either is missing, the upload fails.


        ✅ Fix: Always include both.

      🕒 Why do the dates and times look wrong?

      All dates and times in the API are returned in UTC format. Some endpoints recently started returning date-times instead of just dates, so you might see times you weren’t expecting.


      ✅ Fix: Convert UTC times into your local timezone if needed.

      🏢 Enterprise: Do I need API credentials for every site?

      No. In an Enterprise setup, you only need one set of API credentials on your primary site. These credentials provide access to all linked secondary sites.

      Packages like Jobs, Actions, Adverts, and Placements include data showing which site each record belongs to.


      ✅ Fix: Maintain your API credentials on the primary site only, and use the returned data fields to identify site ownership.

      ⚠ Why am I getting a “500 Internal Server Error”?

      This means something went wrong inside Firefish, usually temporarily.


      ✅ Fix: Try again later. If it persists, contact Firefish Support with details.