Integrate with Approach

Ways to integrate

Approach is a Kuwait marketplace for services, shops, food, tickets, travel and Premium. You can connect in any of the ways below. API methods need a key from us; link and feed methods work with no key at all.

Get API keys

This page is public; your credentials are not. Each partner gets its own key (and, for webhooks, its own signing secret), issued privately and shown to you once. Tell us which method you need, your company name, your technical contact, and, if you want it, the list of server IP addresses your calls will come from.

Base URL and conventions

Partner API calls go over HTTPS to:

https://api.tryapproach.net

• Every path below is relative to this base. There is no /api or version prefix.
• Request and response bodies are JSON. Send Content-Type: application/json on POST and PUT.
• Money is in Kuwaiti dinars (KWD, three decimals). Times are ISO 8601. Calendar dates are Kuwait dates written YYYY-MM-DD with no time zone.
• Every JSON response carries success (true or false). Treat it as the source of truth.

Authentication

Send your secret key in the X-Api-Key header on every request. We store only a hash of it, so we cannot show it to you again; if it is lost we rotate it and the old key stops working at once.

X-Api-Key: apk_your_secret_key_here

A key belongs to one of two kinds of partner. A subscription partner (for example a telecom operator) uses the Premium endpoints. A business partner is bound to one business on Approach and uses the availability endpoints and order webhooks. A key only ever sees its own data.

Errors

Errors use normal HTTP status codes and a JSON body with success: false, a readable message, and the HTTP status repeated as a number in status. Premium endpoints also add a machine readable code (see result codes).

{
  "success": false,
  "message": "Invalid API key",
  "status": 401
}

Limits and retries

• Keep to a steady rate, batch where the API allows (the availability sync takes a full year of dates in one call), and expect a limit to be agreed for high volume.
• Retry 5xx, 429 and network timeouts with exponential backoff. Do not retry other 4xx answers unchanged; fix the request first.
• Activation and the availability sync are idempotent, so a retry after an unclear network error is always safe.
• Webhooks we receive from suppliers are flood guarded per sender IP; a 429 answer carries a Retry-After header in seconds.

Premium provisioning

Grant Approach Premium to your own customers. You identify a customer by Kuwait mobile number; Approach finds that customer's account, or creates one, and turns Premium on. Premium then works everywhere in the Approach app for that number with nothing for the customer to do. Each partner has an agreed plan and price per subscriber and is billed monthly for its active subscribers.

Phone numbers

Send an 8 digit Kuwait number starting with 2, 4, 5, 6 or 9, in any of these forms:

Your reference

Every activation carries your own partnerReference, usually your subscription or order ID. Calling activate again with a reference that is still active changes nothing and answers ALREADY_ACTIVE, so you never create a duplicate. Use the same reference to cancel.

curl -X POST https://api.tryapproach.net/partners/subscriptions/activate \
  -H "X-Api-Key: apk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "msisdn": "+96550123456", "partnerReference": "ACME-SUB-88213" }'

{
  "success": true,
  "ok": true,
  "code": "ACTIVATED",
  "userId": 900123,
  "subscriptionId": 6789,
  "status": "active",
  "expiresAt": "2026-12-05T10:15:00.000+03:00",
  "created": true
}

{
  "success": false,
  "ok": false,
  "code": "INVALID_MSISDN",
  "message": "Not a valid Kuwait mobile number: 1234",
  "status": 400
}

curl -X POST https://api.tryapproach.net/partners/subscriptions/cancel \
  -H "X-Api-Key: apk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "partnerReference": "ACME-SUB-88213" }'

{
  "success": true,
  "ok": true,
  "code": "CANCELLED",
  "userId": 900123,
  "subscriptionId": 6789,
  "status": "cancelled"
}

curl "https://api.tryapproach.net/partners/subscriptions/status?msisdn=%2B96550123456" \
  -H "X-Api-Key: apk_your_secret_key_here"

{
  "success": true,
  "ok": true,
  "code": "ACTIVE",
  "userId": 900123,
  "subscriptionId": 6789,
  "status": "active",
  "expiresAt": "2026-12-05T10:15:00.000+03:00"
}

Result codes

If you send no planId and no default plan is set for you, or you cancel without a partnerReference, the answer is 400 with a message and no code.

Availability sync

For a business on Approach that runs its own booking calendar. Your system tells Approach which days are closed; the Approach app then greys those days out and refuses orders for them. Your key is bound to your business, so you can only ever read and write your own calendars. Days that our team or you close by hand in Approach are never touched by the API.

{
  "success": true,
  "data": {
    "businessUserId": 900001,
    "packages": [
      { "packageId": 77001, "settingId": 4101, "serviceId": 8, "categoryId": 62,
        "title": "Breakfast tray for 10", "titleAr": "صينية فطور لعشرة أشخاص" }
    ]
  }
}

{
  "success": true,
  "data": { "packages": [
    { "packageId": 77001, "closedDates": [
      { "date": "2026-11-20", "source": "api" },
      { "date": "2026-11-27", "source": "manual" }
    ] }
  ] }
}

curl -X PUT https://api.tryapproach.net/partners/availability/dates \
  -H "X-Api-Key: apk_your_secret_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "dates": ["2026-11-20", "2026-11-21"], "packageIds": [77001] }'

{
  "success": true,
  "message": "Availability synced",
  "data": {
    "packagesUpdated": [77001],
    "closedDates": ["2026-11-20", "2026-11-21"],
    "overridesCreated": 2,
    "overridesRemoved": 0
  }
}

Order webhooks

For a business partner with its own system. When one of your orders is paid, cancelled after payment, or has its date or time changed, Approach posts a signed JSON event to your https URL. You only ever hear about money that landed: unpaid orders are never sent.

Request

Content-Type: application/json
X-Approach-Event: order.paid
X-Approach-Event-Id: evt_paid_48213
X-Approach-Timestamp: 1793865164
X-Approach-Signature: sha256=5f0c9a...e41b

{
  "event": "order.paid",
  "event_id": "evt_paid_48213",
  "payloadVersion": 2,
  "orderId": 48213,
  "businessUserId": 900001,
  "serviceId": 8,
  "packageId": 77001,
  "date": "2026-11-20",
  "time": "18:00",
  "customer": { "name": "Sara", "phone": "96550123456", "email": "[email protected]" },
  "address": { "governorate": "Hawalli", "area": "Salmiya", "areaId": 12, "block": "4",
               "street": "Salem Al Mubarak", "addressLine": "Salmiya, block 4, Salem Al Mubarak" },
  "options": [ { "labelEn": "Extra persons", "labelAr": "عدد الأشخاص", "valueEn": null, "valueAr": null, "count": 5 } ],
  "extraGuests": 5,
  "totalAmount": 185.5,
  "currency": "KWD",
  "occurredAt": "2026-11-05T09:12:44.120Z"
}

date (YYYY-MM-DD), time (HH:mm, 24 hour, Kuwait time), packageId, address and totalAmount are filled for package bookings and are null when an order type does not have them. Any detail we cannot read is sent as null rather than holding the event back.

Verify the signature

The signature is the hex HMAC SHA256 of timestamp + "." + rawBody with your signing secret. It is computed fresh on every attempt. Reject events whose timestamp is more than a few minutes old.

const crypto = require("crypto");

function verifyApproach(headers, rawBody, secret) {
  const ts = headers["x-approach-timestamp"];
  const got = String(headers["x-approach-signature"] || "").replace(/^sha256=/, "");
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const want = crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  return got.length === want.length &&
    crypto.timingSafeEqual(Buffer.from(got), Buffer.from(want));
}

Answering and retries

• Answer any 2xx within 10 seconds to accept the event.
• 429, 5xx, timeouts and network errors are retried: up to 6 attempts with exponential backoff starting at 60 seconds.
• Any other 4xx (for example 409 or 422) is treated as your final answer and is not retried.
• Redirects are not followed, so give us the exact final URL.
• The same occurrence keeps the same event_id across retries. Store it and answer repeats with the result you gave the first time.

Digital product suppliers

For suppliers of eSIMs, vouchers, booking codes or insurance policies. This contract runs the other way: you host the API and Approach calls it. When a customer pays, Approach places the order on your API and delivers the result (QR code, activation code, file) to the customer in the app, by e-mail and on a delivery page. If your API already exists in another shape, send us its documentation; we build an adapter for well known platforms instead of asking you to change.

Approach sends your key as Authorization: Bearer <key>, with JSON bodies, and waits up to 12 seconds per call. We call a sandbox base URL first and switch to your live base URL after a test order.

{ "data": [
  { "sku": "TR-7D-5GB", "name": "Turkey 5 GB, 7 days", "countries": ["TR"],
    "data_mb": 5120, "validity_days": 7, "cost": 3.250, "currency": "KWD", "retail": 4.500 }
] }

{
  "sku": "TR-7D-5GB",
  "qty": 1,
  "idempotency_key": "a91c3e0f7b...",
  "customer_ref": "48213-1",
  "email": "[email protected]",
  "start_date": "2026-12-01",
  "end_date": "2026-12-08",
  "destination_country": "TR",
  "documents": [ { "kind": "passport", "url": "https://..." } ]
}

start_date and end_date are sent when the order carries trip dates, and destination_country (ISO 3166 alpha 2) when known. documents (passport, civil_id) is sent only to suppliers who need them, as signed links valid for at most 24 hours.

{ "data": {
  "status": "ready",
  "ref": "ORD-991",
  "lpa": "LPA:1$smdp.example.com$ABC123",
  "activation_code": "ABC123",
  "smdp_address": "smdp.example.com",
  "iccid": "8990000000000000001",
  "confirmation_code": null,
  "file_url": null,
  "install_url": "https://..."
} }

• Answer "status": "pending" when delivery takes time, then send order.completed to our webhook.
• You must treat idempotency_key as unique: a repeated key returns the first order and never buys twice. We retry after timeouts and 5xx, so this is what keeps a customer from being charged twice by you.
• Answer 429 or 5xx for temporary problems (we retry) and other 4xx for a final no.
• GET /orders/{ref} answers { "data": { "status", "activation_status", "usage_mb" } }; cancel answers { "refunded": true } or false.

Supplier webhooks to Approach

We give you a webhook URL that ends in /webhooks/digital/{partnerKey} and a shared signing secret. Send X-Timestamp (unix seconds) and X-Signature, the hex HMAC SHA256 of timestamp + "." + rawBody (a sha256= prefix is accepted). Events older than 5 minutes are refused. A GET or HEAD on the URL answers 200 for your opt in check.

{
  "id": "evt_10023",
  "type": "order.completed",
  "data": { "ref": "ORD-991", "lpa": "LPA:1$smdp.example.com$ABC123", "iccid": "8990000000000000001",
            "install_url": "https://...", "install_url_android": "https://..." }
}

Code stock files

No API? Give us your codes as a CSV file (UTF 8, up to 5,000 rows and 2 MB per file). Each paid order takes the next free code and delivers it at once. The header row names the columns you use:

lpa,activation_code,smdp_address,confirmation_code,iccid
LPA:1$smdp.example.com$ABC123,ABC123,smdp.example.com,,8990000000000000001
,,,VOUCHER-7781,

A supplier can also fill each order by hand: the order waits until the code or file is uploaded, then the customer is notified.

Store catalogue sync

For online stores. Give us your store's website and we read its public product list. Supported today: Shopify, WooCommerce, MNASATI and Bilbayt.

• Auto pull brings in products that are not on Approach yet: name (Arabic too when your site has it), description, price, crossed out price, stock and up to 5 photos. New products wait hidden for review unless you ask for them to go live straight away.
• Auto sync keeps price, sale price and stock in step on a schedule you choose (every 24, 48, 72 hours or weekly). It never deletes or hides products and never changes photos or names.
• Safety holds: if your site answer looks wrong (unreachable, much smaller than before, or a price moving below 30% or above 3 times its value), nothing changes for that run.
• Products whose sizes have different prices are added by hand.

Assisted onboarding

Not on one of those platforms? Send us your menu, price list or spreadsheet with photos. Our team builds your catalogue on Approach, including options and add ons, and you preview it before it goes live.

Links and deep links

Every public Approach page has a stable link you can put on your site, in an e-mail or in an ad. On phones that have the Approach app, supported links open straight in the app (iOS Universal Links, Android App Links); everyone else gets the web page or the download page.

A link without /ar or /en picks the visitor's language (Arabic by default).

Referral tag

We issue you a code and ready made order links that carry it as ?ref={yourCode}. When a customer opens one of those links on a phone with the Approach app, the app keeps the code for 24 hours and every order placed in that time is tagged to you, so we can report it.

Feeds and structured data

The feeds refresh every 30 minutes and list only products that are on sale to the public; each item links to its product page. Product pages carry schema.org Product data with the same price and availability; business pages carry LocalBusiness, category pages CollectionPage, and Premium packages Service.

Payment links and checkout

Payment links

Our team creates a payment link for any amount with a description, in your business's name and logo. The customer opens a secure page on pay.tryapproach.net, picks a payment method and pays; the link expires after the time set for it and can be sent by SMS. Paid links settle to your business like any order.

Web checkout

Shops and services can be ordered and paid on tryapproach.net with no app and no login. After an order, the customer gets a WhatsApp message with a private link to the order page: status, price breakdown and payment. Tickets stay in the app.

Payment methods

KNET, Visa and Mastercard and Apple Pay are processed by UPayments; pay later in instalments is offered through Taly in the app. These are Approach's own payment rails: partners do not integrate with them directly, and card details never reach Approach or you.

Business tools

• Business account in the Approach app: accept or reject orders, set prices, packages, options, opening hours and closed days, publish stories and offers.
• Business dashboard: a web login (sent by e-mail when you join) with your orders, packages, calendar, transfers and a printable monthly report.
• Notifications: push on every new order and status change, a WhatsApp message for new and paid orders, and e-mail for account messages. If a customer has an urgent issue they can send one emergency message per order, which reaches you by WhatsApp.
• Visa providers: receive each visa application with its travellers and their passport and civil ID copies, download all documents as one ZIP, and move the application through its stages while the customer is kept up to date.
• Event organizers: we set up the event, seat map and prices; tickets sell in the app, can be transferred between customers, and your gate staff scan them with the Approach app. Sales reports are available during and after the event.

To join as a business, apply at tryapproach.net/en/become-an-approacher.

Security

• Keep keys and signing secrets on your servers only. Never put them in a mobile app, a web page or a public repository.
• Always call over HTTPS, and give us an https webhook URL.
• Send us your outbound IP addresses so we can lock your key to them.
• Verify every webhook signature and timestamp before you act on it.
• If a key or secret may have leaked, ask us to rotate it. The old one stops working immediately.

Support and onboarding

To go live we agree the method, test it with you, then issue your live credentials. For the Premium API that includes your plan and price; for suppliers, a test order on your sandbox.