How multi-provider API integrations work

Two systems can use the same word and mean different records. A desk stores an item a person can book. A provider that feeds the public list stores a listing. In a meeting both sides say “title”. One string is “Thursday session, returning visitors”. The other is “Thursday session”, with the audience kept in a field beside it. An import that matches on the text creates a second item the moment the provider edits the string.

One noun

Stop the integration at the noun. For this pair of systems the noun is a listing: a thing a person can book, with a stable identity, a display name, a time, and a status. The desk’s internal record may also carry staff notes. The provider’s campaign record may carry announcement text. Those are other nouns. They can be joined later.

The display name may change. The identity stays. The desk stores the provider’s identifier as the provider gave it, and it stores its own identifier for the row. Matching uses the provider identifier. The display name is what a person reads.

A rename then has a dull and correct result. The provider changes “Thursday session” to “Thursday session, returning”. The desk finds the row by the provider identifier and changes the display name. Notes typed on the desk stay on the desk’s own row.

A second provider

A second provider arrives with its own identifier and its own names. The noun keeps one shape. The new provider supplies a listing identity, a display name, a time, and a status. Where that provider says event, session, or title, the map into the noun is written beside the integration:

• eventId is the listing identity.
• label is the display name.
• start is the time.
• A missing status means the listing is withheld, and the desk shows nothing for it.

A missing status withholds the listing because the written map says so. The person running the desk can see that reason. The method is to follow the map and to leave a blank as a blank.

The calls that carry this noun are a timetable: API orchestration for a B2B platform. When the thing being opened is a playable title rather than a listing, the platform also keeps a session: Session architecture for a multi-provider platform.

Match on the identifier, then rename

The provider changes “Thursday session” to “Thursday session, returning.” The desk finds the row by the provider identifier and changes the display name. Notes typed on the desk stay on the desk’s own row. An import that had matched on the text would have inserted a second item and left the notes on the old one. The public list would show both, and a person would book the stale name.

Write the identifier down as the provider sent it. Do not trim it, and do not rebuild it from the display name. A rebuilt identifier changes whenever the name changes, which is the bug the match was meant to avoid.

A second provider enters the same shape

The new provider says event, session, or title. The map beside the integration says which of its fields is the listing identity, which is the display name, which is the time, and what a missing status means. In this example a missing status withholds the listing, and the desk shows nothing for it. The person running the desk can see that reason. A blank is not filled with a guess.

If the new provider has no stable identity, stop. Do not promote the display name into an identity “for now.” That promotion is the second item, waiting for the first rename.

Nouns that are not the listing

Staff notes on the desk are a different noun. Announcement text on the provider is a different noun. They can be joined later, by the listing identity, when someone has a reason to show them. Pulling them into the listing on the first import makes every provider’s extra field look required. The next provider will not have that field, and the listing shape will grow a hole.

Keep the listing to identity, display name, time, and status. Say the other nouns out loud in the meeting so they are not smuggled in under the word “title.”

What you can check without a live call

Take one listing the provider has already described on paper. Write the desk’s row by hand from the map. Change only the display name on the paper and write the row again. You should still be pointing at one desk row. Change the provider identifier and you should be pointing at a second row, even if the display name matches. Those two results are the integration. The timetable of calls comes after the noun is this dull.

The paper before the call

Write one listing on paper the way the provider’s own description already has it, using their field names. Beside it, write the desk’s row using only the four fields this piece allows: identity, display name, time, and status. Draw arrows from their fields to those four. If one of their fields has nowhere to go, it is not part of the listing. It is another noun, and it stays on the paper’s margin until someone has a reason to show it.

Do this before anyone writes a client. A client written first will grow a field for every key in the payload, and the second provider will not have those keys. The shape you wanted, one noun, will be the first provider’s payload with a new name. The paper is how you notice that while the arrows are still erasable.

Identity is the provider’s stable id, not the display name. Two listings can share a display name and still be two rows. One listing can change its display name and must remain one row. If your arrows use the display name as identity, redraw them. The check without a live call is exactly this: change the name, same row; change the id, second row.

Status is a small vocabulary

Status on the desk is a word you chose, not the provider’s word. Offered and withdrawn are enough to start. A provider that says “inactive,” “archived,” or “hidden” has to be mapped into that pair, or into a third word you add on purpose and write down. Do not store the provider’s word raw in the desk row and also store your word. Two status fields is how a listing is offered on the desk and withdrawn on the provider, and the timetable publishes it anyway.

When you add a third status, add it because a weekday needs it, not because the payload had a third string. Write the weekday next to the word. “Pending” with no weekday is a junk drawer. The next provider will send a different third string, and you will have two junk drawers.

The second provider on the same paper

Take a second provider’s listing, different field names, same four arrows. If you have to add a fifth field so the second listing “fits,” stop. Either the fifth field is another noun, or the first provider was allowed to define the noun. Rename both into the four. A field that only one provider has can live beside the row, joined by identity, when a screen actually shows it. It does not become required on the row.

Staff notes written on the desk are that kind of neighbor. Announcement text that lives only on one provider is that kind of neighbor. Say those nouns out loud in the meeting so they are not smuggled in under the word “title.” Title, in this piece, is the display name. It is not a bag.

What you hand the timetable

Hand across the paper, the four fields, and the two checks: same id keeps one row, new id makes a second row. The timetable is not allowed to invent a fifth field because a call returned one. If a call returns a surprise key, the surprise stays off the public row until the paper grows an arrow for it. A surprise published because it was present is how the noun stops being dull.

The session clock, later, stores identity too: which provider, which title. It stores that identity from this noun, not from a second naming scheme invented at session time. If the noun is still mushy, the clock will store mush. Finish the paper first.

A display name that is only a display name

The display name is allowed to be messy, duplicated, and rewritten overnight. The desk shows it. The desk does not look up by it. Search on the desk can prefer the display name for a person typing, and the row it opens is still the one the identifier points at. If two rows share a display name, the search shows both, with the identifier visible enough that a person can tell them apart. Hiding the identifier because it looks like a database key pushes people to merge rows that are not the same listing.

When a provider sends an empty display name, store the empty name and show a dull stand-in on the desk, “Untitled listing,” without writing that stand-in back as if the provider had said it. The next import must be free to fill the real name. If you save the stand-in as the provider’s name, you have invented a field the provider did not send, and the following import will treat the real name as a change that needs a story.