> For the complete documentation index, see [llms.txt](https://developers.share.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.share.inc/getting-started/first-request.md).

# Your first request

This guide walks you from "we just provisioned your credentials" to "I made a successful API call and parsed the response" in about five minutes.

By the end you will have:

1. Found your `X-Access-Id` and `X-Access-Secret` credentials
2. Made a `GET /v1/subscribers` call against the API
3. Read the response envelope, including the `success` flag and pagination
4. Understood what a non-2xx response looks like and how to react to it

## What you need

| Item                    | How to get it                                              |
| ----------------------- | ---------------------------------------------------------- |
| `X-Access-Id`           | Provisioned by Share when your partner account was created |
| `X-Access-Secret`       | Same — kept separately, treat it as a password             |
| Base URL                | `https://api.share.inc` (production)                       |
| `curl` or any HTTP tool | Anything that can set request headers                      |

If you do not have credentials, contact your Share account manager. The credentials are scoped to a single partner ("provider") and identify both who you are and what data you can see.

## Step 1 — Send the request

```bash
curl -sS https://api.share.inc/v1/subscribers \
  -H "X-Access-Id: <your-access-id>" \
  -H "X-Access-Secret: <your-access-secret>" \
  -H "Accept: application/json"
```

Two notes:

* The credentials go in **headers**, not a query string. They are scoped to the partner — see [Authentication](/getting-started/authentication.md) for the full spec.
* The Share API is versioned in the URL path (`/v1/...`). Future versions will not break v1 — see [Changelog](/changelog/changelog.md).

## Step 2 — Read the response envelope

Every Share API response is wrapped in the same envelope. A successful list call looks like this:

```json
{
  "success": true,
  "data": [
    {
      "id": "sub_01HXYZ...",
      "firstName": "Amina",
      "lastName": "Otieno",
      "phone": "+254712345678",
      "createdAt": "2026-05-10T08:14:22.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

The envelope is guaranteed across every endpoint:

| Field              | Meaning                                                                   |
| ------------------ | ------------------------------------------------------------------------- |
| `success`          | `true` for 2xx responses, `false` for 4xx/5xx                             |
| `data`             | The actual payload — an object on single-resource calls, an array on list |
| `meta`             | Pagination metadata — only present on paginated endpoints                 |
| `error`            | Short error code — present only when `success` is `false`                 |
| `rejectionReasons` | Field-level validation errors — present only on validation failures       |

Treat `success` as the canonical signal. Do **not** rely on HTTP status alone — some intermediaries strip or rewrite it. `success: true` ⟺ the call did what you asked.

## Step 3 — Handle a failure

If you flip one character in the secret and re-send:

```bash
curl -sS https://api.share.inc/v1/subscribers \
  -H "X-Access-Id: <your-access-id>" \
  -H "X-Access-Secret: WRONG" \
  -H "Accept: application/json"
```

…you get a 401 with this body:

```json
{
  "success": false,
  "error": "UNAUTHORIZED"
}
```

A 400 from validation (e.g. an invalid query parameter) looks like:

```json
{
  "success": false,
  "error": "VALIDATION_FAILED",
  "rejectionReasons": [
    {
      "field": "page",
      "code": "MUST_BE_POSITIVE_INTEGER",
      "message": "page must be a positive integer"
    }
  ]
}
```

`rejectionReasons` is the field you want to surface to the end user — it maps 1:1 onto form fields. The top-level `error` is the machine-readable code; see [Error codes](/errors/error-codes.md) for the catalog.

## Step 4 — Make a mutating call (idempotently)

Read calls are safe to retry. Mutating calls (`POST`, `PATCH`, `DELETE`) should carry an `Idempotency-Key` so you can retry on network failure without double-charging or double-creating.

```bash
curl -sS https://api.share.inc/v1/subscribers \
  -X POST \
  -H "X-Access-Id: <your-access-id>" \
  -H "X-Access-Secret: <your-access-secret>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "firstName": "Amina",
    "lastName": "Otieno",
    "phone": "+254712345678"
  }'
```

If the request times out and you retry with the **same** `Idempotency-Key`, Share returns the original response instead of creating a duplicate. See [Idempotency](/getting-started/idempotency.md) for the full semantics.

## Common pitfalls

* **Sending credentials as `Authorization: Bearer ...`** — Share uses the header pair, not Bearer tokens. See [Authentication](/getting-started/authentication.md).
* **Trusting HTTP status only** — always check `success` in the body.
* **Skipping `Idempotency-Key` on `POST` / `PATCH`** — fine in a sandbox, dangerous in production. You will eventually retry a 502 from a load balancer that did fire the original write.
* **Logging the full `X-Access-Secret`** — redact it the same way you redact passwords.

## Next steps

* Read [Authentication](/getting-started/authentication.md) for the header-pair contract
* Read [Idempotency](/getting-started/idempotency.md) before doing your first `POST` in production
* Walk through [Onboard a subscriber](/guides/onboard-a-subscriber.md) for an end-to-end use case that combines several endpoints
* Skim the [API Reference](/api-reference/api-reference.md) for the full endpoint surface