Your first request

This walkthrough uses the Pro account OAuth pilot at https://api.fisk.co.tz. You need a manually registered and enabled OAuth client, an exact approved callback URL and a valid connector access token. See authentication first; the API URL alone does not enable a client.

1. Set your environment

Keep access tokens in your backend’s secret store or a local environment. Do not commit them or put them in URLs.

export FISK_API_URL="https://api.fisk.co.tz"
export FISK_ACCESS_TOKEN="your-short-lived-access-token"

Replace the access-token placeholder with the short-lived token issued through your approved OAuth connection. There is no shared public demo credential.

2. Find a company

Search by literal company name or ticker. A company ID remains the identifier for subsequent requests.

curl --fail-with-body --get "$FISK_API_URL/v1/companies" \
  --data-urlencode "query=KCB" \
  --data-urlencode "limit=5" \
  -H "Authorization: Bearer $FISK_ACCESS_TOKEN"

Read data[].id and data[].exchange in the result. Choose the intended listing; a name alone is not a unique market identifier.

3. Retrieve a financial metric

Set COMPANY_ID to the UUID from the previous response.

curl --fail-with-body --get \
  "$FISK_API_URL/v1/companies/$COMPANY_ID/financials" \
  --data-urlencode "metric=net_income" \
  --data-urlencode "limit=5" \
  -H "Authorization: Bearer $FISK_ACCESS_TOKEN"

For each returned fact, retain currency, period_start, period_end, entity_scope, restated, source_url and page_number alongside value.

value is already in base units and is a decimal string. Do not multiply it by unit_multiplier again. See sources, units and freshness.

4. Inspect the source

Use a returned document_id and page_number to retrieve a page excerpt.

curl --fail-with-body \
  "$FISK_API_URL/v1/documents/$DOCUMENT_ID/pages/$PAGE_NUMBER" \
  -H "Authorization: Bearer $FISK_ACCESS_TOKEN"

The response includes up to 6,000 characters, an original source URL and a Fisk document link. If truncated is true, the excerpt is incomplete.

In a backend application

const response = await fetch(
  `${process.env.FISK_API_URL}/v1/companies?query=KCB&limit=5`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      Accept: "application/json",
    },
    signal: AbortSignal.timeout(10_000),
    cache: "no-store",
  },
);

if (!response.ok) {
  const failure = await response.json();
  // Handle auth and quota failures explicitly; do not retry every error.
  throw new Error(
    `${failure.error.code}: ${failure.error.requestId ?? "no request id"}`,
  );
}

const { data, meta } = await response.json();
// Render the chosen listing and preserve source/freshness context.

Add specific error handling before using this in a customer-facing flow.