FreshService API Testing & Diagnostics
The FreshService data source editor has a FreshService API Testing tab: a set of tools for proving that the connection, the API key's permissions and the field metadata a migration relies on are actually working. Use it when a migration to FreshService fails, returns less than you expected, or when you need to hand FreshService support an accurate picture of a request.
Open the FreshService data source from Admin → Data Sources and select the FreshService API Testing tab. The tab is available on every FreshService data source.
Only one tool on this tab writes anything: Attachment Tester uploads a file to a ticket you name. Everything else reads from FreshService, or builds a request and shows it without sending it.
The tools
| Sub-tab | What it does |
|---|---|
| Introduction | Describes the toolkit and what each sub-tab is for. |
| Custom Request | Sends an arbitrary request and shows the raw response, the API's own error message, the rate-limit headers and the exact URL Cortex used. Enter the path after /api/v2/ and use GET Request or POST Request - the body box is only sent with a POST. |
| Endpoint Probes | Calls each endpoint Cortex itself uses, one click for all of them, with your configured workspace applied to the ticket endpoints. The grid reports the HTTP status, the API's own reason, what the key's role must be allowed to do (Needs), and a summary; open a row to read the full response body. |
| ID Lookups | Lists the account's groups, agents, requesters and departments, and resolves a single id to its name. Ids never carry over from a source system, so this is how you confirm that a group, agent or requester id used by a mapping exists on the target account. |
| Permission Report | Reports per endpoint whether the API key is allowed - OK, 403, 401 or 404 - together with the API's own code and message and what the result means. |
| Field Inspector | Shows the ticket field definitions Cortex imported, flags choices that carry a value but no display label (the cause of blank entries in the mapping grid), and lists each field's dependent levels. |
| Ticket Inspector | Reads a named ticket and shows the flags - deleted, spam, status - that decide whether a follow-up write can ever succeed. It also decodes a write refusal, such as PUT method is not allowed. It should be one of these method(s): GET, by reading the allowed-methods list the API returned. |
| Write Request Preview | A visual field editor for the request a create would send. Pick a table and every writable field it accepts is listed; select a field, enter the value to send, and add modifiers from Cortex's own modifier editor (trim, upper case, lower case, format date, remove text, text before/after, JSON operations and so on). Each field shows the value as it would be sent, and Build Preview shows the request a real insert would put on the wire - the method, the full URL, the headers with the API key masked, and the pretty-printed JSON body. Nothing is sent and no record is created. |
| Attachment Tester | Uploads a chosen file to a named ticket using the same multipart update Cortex uses for migrated attachments. This is a real write: the file is attached to that ticket. |
| Resolved Tables & Fields | The tables and fields Cortex resolves for this data source, as the rest of the application sees them - the way to confirm that imported custom fields, and their types, reached the tickets table definition. |
| Diagnostics | The stored configuration for the data source, plus Copy Diagnostic Block - a summary you can paste into a support request. The API key is never part of the copied block. |
Wherever the API key appears on this tab it is masked. It is only revealed from the Connection Details tab, with its Reveal toggle.
A successful Test Connection does not prove permissions
Test Connection on the Connection Details tab calls one endpoint (tickets), which any full-time agent can read. FreshService restricts other endpoints - workspaces, groups, agents and departments - to an admin role, so a 403 from Endpoint Probes on a key that has just tested successfully is a missing permission, not a broken connection. access_denied means the key itself is valid but the role its agent holds is not allowed to make that call.
Use Identify the key's agent on the Endpoint Probes sub-tab to see whose API key Cortex is using, then grant that role the permission named in the Needs column.
Common failures and where to look
| Symptom | Where to look |
|---|---|
403 access_denied on some calls but not others | Permission Report and Endpoint Probes - the endpoint needs a role the key's agent does not have |
| A write is refused with a method-not-allowed message | Ticket Inspector - the ticket is deleted or spam (it still answers a read, but every write is refused), or the API's allowed-methods list names the reason |
missing_field naming a field you did map | Write Request Preview - build the request for that table and field to see the value, and whether the field is accepted at all |
| A dropdown or mapping option appears blank | Field Inspector - the choice has a value but no display label |
| A mapped group, agent or requester id resolves to the wrong name, or to nothing | ID Lookups - ids are per account and do not come across with the migrated data |
| You need the exact URL, headers and body Cortex sends | Write Request Preview (a create) or Custom Request (any path) |
| You are raising the problem with FreshService support | Diagnostics → Copy Diagnostic Block, plus the output of the tool that showed the failure |
See also
- Data Sources - adding a FreshService connection to Cortex
- FreshService as a Migration Target - connection settings, workspaces, ticket fields and rich-text handling
- Field Mappings - mapping source fields to FreshService fields
- API Call Statistics - how many API calls Cortex issues to a data source, against its rate limit