Skip to content

Webservice Cookbook — Introduction

These articles take you through connecting IMan to a REST API, and then reading, looking up and writing data across it.

They are not a reference. The Webservices section of the User Guide describes what every field on every screen does. These articles do the thing a reference cannot, which is show you how to get from a vendor's API documentation to a working IMan setup.

That translation is the difficult part, and it is different for every service. No two vendors describe authentication in the same words, few of them use IMan's vocabulary, and the sentence that decides a setting is rarely the sentence that looks important. Each recipe therefore quotes the vendor's own documentation beside the screen it determines, and says which words did the deciding.

The services

Seven services, chosen because between them they cover every shape IMan has to deal with.

Service What it is What it is here for
Xero Cloud accounting The spine. Three-legged OAuth, then reading, looking up, writing and replaying the response
Mailchimp Marketing email Textbook Basic authentication — any string as the user, the API key as the password
JIRA / Atlassian Issue tracking Basic authentication, but an email address and an API token rather than a password
Todoist Task management A static token on Authorization: Bearer — the commonest pattern in modern APIs
Klaviyo Marketing automation A non-standard prefix on the standard header, plus a second header the API requires on every request
PayPal Payments Two-legged OAuth — client credentials, no user consent
Zoho CRM and business apps Three-legged OAuth a second time, against a vendor that documents it differently — and that binds a token to a data centre

Xero carries every article from the Webservice Behaviour onwards. One service throughout means the reader and the writer are two ends of the same integration rather than two unrelated exercises, and it means the paging, throttling and error handling you set up once are the ones you keep using.

The other six appear in the authentication articles, because authentication is the part of a webservice setup where vendors vary most. Mailchimp comes back once more, in Webservice Lookup, for a case Xero cannot show: an endpoint that will not filter, so the matching has to happen in the return path.

Before you start

Accounts. Every service above offers a free account or a free developer sandbox, and the recipes are written to stay inside them. You do not need all seven — take the ones for the articles you are working through. Where a service needs a specific kind of account, such as a Xero demo organisation or a PayPal sandbox account, the article says so.

Credentials are yours, and they are real. These recipes produce working API credentials. IMan stores them so that they can be sent, which means they can also be read back by anyone with access to the Setup screens — a Basic Authentication shows its assembled header in plain sight, by design, because that is how a broken setup stays diagnosable. Use credentials you are willing to have on a shared IMan, and revoke them at the vendor when you have finished.

Work in this order. The two authentication articles come first and the rest follow in sequence.

The OAuth article is not optional. Everything from the Webservice Behaviour onwards runs against Xero, and Xero is OAuth 2.0 only — there is no API key and no Basic option. Complete the three-legged Xero setup before you reach it. Read the Basic Authentication article first even so: it introduces the HTTP header model that the OAuth screens reuse.

Articles

  • Basic Authentication
    • Authentication as a set of HTTP headers, the form almost every non-OAuth service comes down to.
    • Covers the three Authorisation Types — Basic, Bearer and Raw — and which sentence in a vendor's documentation tells you which one you are looking at.
  • OAuth 2.0 Authentication
    • The other authentication protocol IMan supports, and the one Xero requires. Which of the two flows a service needs, and what to have in front of you before you start.
    • Two-Legged OAuth 2.0 works the client credentials flow through against the PayPal REST API.
    • Three-Legged OAuth 2.0 works the authorisation code flow through against Xero, and is the one the rest of this cookbook depends on. It then does it a second time against Zoho, because the differences between two vendors running the same flow make it learnable rather than memorable.
    • Diagnosing an OAuth Setup covers what each failure means, which is rarely what it says.
  • Webservice Behaviour
    • The Webservice Behaviour groups the traits shared by every request to a service — authentication, paging, request throttling and tracing. Almost every service needs one, because it associates an authentication with a request.
    • This article builds the Xero behaviour used by every article after it.
  • Reading Data from a Webservice — JSON Reader
    • Setting up a JSON Reader to read from Xero.
  • Using the Stepped Reader
    • Stepped Readers make several requests to build a single dataset — a first call for a list, then a call per item for its detail.
    • This article configures a Stepped JSON Reader against Xero.
  • Webservice Lookup
    • How to use Webservice Lookups to run translation and validation logic against a service from anywhere in an integration.
    • Two of them: a Xero lookup that finds a contact's id from its name, and a Mailchimp one that filters in the return path because the endpoint will not filter for it.
  • JSON Writer — Flat Data
    • Writing to Xero, both creating records and modifying existing ones, and the general webservice concepts that go with each.
  • Replaying Response Data
    • How to write a service's response back onto the IMan dataset — specifically, capturing the ids Xero generates for the records you have just created.

Keeping this current

Everything here asserts something about a service we do not control. Vendors change authentication, retire endpoints and rewrite their documentation, and none of that fails our build.

Each article therefore ends with the date it was last checked end to end against the live service, on the IMan version named. If a screen no longer matches what you see, the vendor's own documentation wins — and please tell us, because the article is wrong.

Verified against IMan 6.1 on 2 September 2026.