Provider integration

1. How it fits together

You build a map for your workbook in Excel, as any user does. As a provider you then publish a version of that map, and you tell us which organisations are your clients. From that moment everyone in those organisations sees your map in their modelflow pane and can fill your workbook with it.

Your clients do nothing and pay nothing. There are no seats to assign on their side and no invitation to accept. You are billed monthly for the people who actually used your maps, and the statement shows you which client that was, so you can pass it on.

You do not have to build or host anything. Maps are built, published and retired by a person: in Excel and in the provider portal. The API exists for the two jobs a system does better than a person: keeping your client list in step with your CRM, and fetching the monthly statement for your own invoicing. Both can also be done by hand in the portal.

2. Becoming a provider

Sign in at app.trymodelflow.com with your work account and open the provider portal. Activating provider mode starts a separate subscription: a platform fee, plus the active users at your clients, billed monthly in arrears. Your first API key is created with it.

The portal is where you create API keys, publish your maps, and see your clients and statements. A firm with twenty clients can manage them there by hand. A firm with a CRM will want the client sync below.

3. Authentication

The API is authenticated with a provider API key, not with a user sign-in, so it can run unattended in your CRM or a nightly job. Send the key in the x-provider-key header, or as a bearer token.

A key is shown once, when it is created. We store only a hash of it and cannot show it again. You can hold several live keys at the same time, which is how you rotate one: create the new key, switch your system over, then revoke the old one.

The base address is https://app.trymodelflow.com/v1/provider. Requests and responses are JSON. A key does three things: it reads the overview, adds and removes clients, and reads statements. Everything else, including creating and revoking keys, is done by a signed-in person in the portal. Those addresses do not accept a key at all and answer it with 401. Requests are limited to 600 per minute per provider.

curl https://app.trymodelflow.com/v1/provider \
  -H "x-provider-key: mf_..."

4. Adding clients

You identify a client by a domain they sign in to Microsoft 365 with. We resolve the domain to their Microsoft organisation, and everyone in that organisation is entitled to your published maps. Several domains of one client belong in the same entry. The reference is yours, typically the CRM number, and it comes back on every statement line.

Send one client or a whole list. Adding a client that already exists changes nothing except its reference, so you can post your full client list every night without keeping track of what changed.

One bad domain never rejects the rest. A domain we cannot resolve yet is stored and retried, because the client may not have finished their own Microsoft 365 setup. It is listed under warnings with the reason tenant_not_resolvable, and it becomes active by itself once it resolves.

curl -X POST https://app.trymodelflow.com/v1/provider/customers \
  -H "x-provider-key: mf_..." \
  -H "content-type: application/json" \
  -d '{
    "customers": [
      { "domains": ["client.com", "client-group.com"], "reference": "CRM-4417" },
      { "domains": ["other-firm.nl"], "reference": "CRM-4418" }
    ]
  }'

The response counts what happened:

{
  "added": 1,
  "unchanged": 1,
  "warnings": [{ "domain": "other-firm.nl", "reason": "tenant_not_resolvable" }]
}

5. Removing a client

Removing a client ends their access at the end of the current billing period, not immediately. Someone in the middle of a year-end closing keeps working until the month is over. The id is the one returned by the overview call, GET on the base address, which lists your keys, clients and published maps.

curl -X DELETE https://app.trymodelflow.com/v1/provider/customers/{id} \
  -H "x-provider-key: mf_..."

6. Publishing maps

Publishing is done by a person in the provider portal, not through the API. A map is built in Excel against your workbook, so there is nothing a script could publish on its own. In the portal, every map of your organisation is listed with its current version and a publish button.

You publish a specific version of a map, not the map as such. Several versions can be live at once, and your clients see every version that is not retired. That lets them move to a new release of your workbook when it suits them, instead of on the day you publish.

Retiring a version hides it from new runs and never interrupts one that is under way.

7. Statements

There is one statement per calendar month, issued together with your invoice and carrying the same numbers. GET on /statements lists the months. GET on /statements/{YYYY-MM} returns one of them.

Each line is one client: your reference, the number of active users, the number of fill runs, and the map versions they used. A statement is final once issued and is never recalculated.

You only ever see usage of your own maps. What a client does with maps of their own, or with those of another provider, is not visible to you.

curl https://app.trymodelflow.com/v1/provider/statements/2026-08 \
  -H "x-provider-key: mf_..."

{
  "period": "2026-08",
  "issuedAt": "2026-09-01T00:04:11.000Z",
  "totalActiveUsers": 14,
  "billableUsers": 14,
  "lines": [
    {
      "customerTenantId": "6d0f...",
      "customerName": "Client GmbH",
      "reference": "CRM-4417",
      "activeUsers": 9,
      "runs": 61,
      "mapVersions": ["Valuation model v2"]
    }
  ]
}

8. What counts as usage

An active user is a person who completed at least one fill run with one of your published maps in that calendar month. Someone who signed in but never ran a fill does not count. Someone who ran a hundred fills counts once.

The count starts from zero every month. Your invoice is the platform fee plus the active users of the month, with the minimum agreed in your plan. Nothing is ever charged to your clients by us.

If a client is also a modelflow customer in their own right, or is entitled by a second provider, nothing is mixed up: usage is attributed to the map. Runs with your maps are yours, all others are not.

9. Errors

Errors come with an HTTP status and a body that names a stable code. 401 means the key is missing, wrong or revoked. 403 with account_closed means your account has been closed. 404 names what was not found. 429 means you are over the request limit, and the call can simply be repeated a minute later.

{ "error": { "code": "customer_not_found", "message": "Customer not found" } }

10. If a payment fails

A failed payment on your side does not cut your clients off. They keep access for 14 days while the payment is retried, and you are told at once. Only when that period runs out are your maps withheld from them, and they come back as soon as the invoice is paid.