Card status and picked places

---

You can now check a person's card before you build for them, and ask for exactly the restaurants your app shows instead of sorting search results yourself.

What changed

• GET /v1/users/{userId} answers id, status, authorized and card, with your secret key. card is { "onFile", "orderable", "brand", "last4" } for the card Layout would charge, and null until the person has authorized your application. See GET /v1/users/:id.
• The verify answer carries the same card once authorized is true.
• A cart read on a build grant now carries card, the card that will be billed, so your confirm screen can name it. It used to be null on a build grant.
• query on GET /v1/places takes up to three names separated by commas, such as sweetgreen,chipotle,cava. Each is searched and they come back as one list: each place once, open places first, then nearest first. Each name counts as one place read and answers at most 10 places.
• ids on GET /v1/places reads up to 25 places you already picked, in the order you sent them, with their status now. Closed places are included, each id counts as one place read, and an id Layout no longer holds comes back in missing.
• include=closed also lists places that are shut now or whose hours Layout does not hold, after the open ones, from the places Layout already holds. ordering=confirmed lists only places where Layout has found an online ordering route, and an empty answer says emptyBecause: "none_confirmed".
• limit goes up to 25, from 10.
• Every place carries lat, lng, closesAtIso and opensAtIso, on GET /v1/places and GET /v1/places/{placeId}.

Why it matters

Until now the only way to learn that a person had no card was to build and get card_required back, and the only proof a card link worked was the return URL, which anyone can open. Now you can send a card link right after verify when card.orderable is false, and confirm a status=card_added return from your server.

An app built around a few chains, or a short list of restaurants, can ask for exactly those in one call and render the answer as it comes, with coordinates for a map and instants it can compare to its own clock.

What to do

Nothing, unless you want the new behaviour. To check a card after verify:

curl https://api.layout.link/v1/users/usr_4b8e9a01c2d3 \
  -H "Authorization: Bearer $LAYOUT_SECRET_KEY"

200 OK
{
  "id": "usr_4b8e9a01c2d3",
  "status": "active",
  "authorized": true,
  "card": { "onFile": false, "orderable": false, "brand": null, "last4": null }
}

To show a chain app's stores near the person, open ones first:

curl "https://api.layout.link/v1/places?query=sweetgreen,chipotle,cava&lat=37.78&lng=-122.41&limit=25&include=closed" \
  -H "Authorization: Bearer $LAYOUT_PERSON_TOKEN"

To refresh places you saved:

curl "https://api.layout.link/v1/places?ids=ChIJbloomCoffee,ChIJtacoSpot&lat=37.78&lng=-122.41" \
  -H "Authorization: Bearer $LAYOUT_PERSON_TOKEN"

In sandbox every verified person reads as holding a test Visa ending 4242, because a sandbox build never needs a card. A sandbox cart's card is null, since nothing is charged.

Breaking changes

A comma in query now separates names. A query that used one as punctuation, such as coffee, San Francisco, is now two searches that count as two place reads, and a query with more than three names is a 400 invalid_request. Put a place in near instead. Nothing else changes for existing calls: every other field is new, and a build grant's cart now fills card where it was null.

All changes