protrakApiClient

Reference

A low-level HTTP client for making direct Protrak REST API calls. Handles authentication headers automatically. Use protrakApiClient inside a promiseFn when you need to chain or combine multiple API calls.

const { protrakUtils } = React.useContext(customWidgetContext);
const { protrakApiClient } = protrakUtils;

Prefer useProtrakApi for single API calls. Use protrakApiClient directly only when you need to build a custom promiseFn (e.g., sequential or parallel calls, post-processing).

---

Signature

protrakApiClient(endpoint, config);

Parameters

Param	Type	Description
endpoint	string	API path relative to the Protrak base URL, e.g. 'instances/abc-123'
config.method	string	HTTP method: 'GET', 'POST', 'PUT', 'DELETE', 'PATCH'
config.params	object	Query string parameters (for GET requests)
config.data	object	Request body (for POST / PUT / PATCH)
config.headers	object	Extra HTTP headers (merged with defaults)

Returns

Promise — resolves to the API response data, or rejects on error.

---

Usage Example

Inside a promiseFn — sequential API calls

const createAndLinkNote = async ({ instanceId, noteName }) => {
  // Step 1: create the note
  const newNote = await protrakApiClient('instances', {
    method: 'POST',
    data: { typeName: 'Notes', name: noteName },
  });

  // Step 2: link it to the parent instance
  await protrakApiClient(`instances/${instanceId}/relatedInstances`, {
    method: 'POST',
    data: {
      relatedInstanceId: newNote.id,
      relationTypeName: 'AgreementToNotes',
    },
  });

  return newNote;
};

function AddNoteWidget(pageContext) {
  const { protrakUtils, protrakComponents } =
    React.useContext(customWidgetContext);
  const { useProtrakApi } = protrakUtils;
  const { Button, ButtonEnums, Spinner, Text } = protrakComponents;

  const { state, run } = useProtrakApi(
    {
      promiseFn: createAndLinkNote,
      instanceId: pageContext.instanceId,
      noteName: 'Quick Note',
    },
    {
      defer: true,
      onSuccess: () => {
        pageContext.reloadInstanceDetails();
      },
    }
  );

  if (state.isLoading) return <Spinner />;

  return (
    <Button
      text="Add Note"
      appearance={ButtonEnums.Appearance.Primary}
      onClick={() => run()}
    />
  );
}

GET request with query params

const fetchInstances = async ({ instanceType, skip, take }) => {
  return await protrakApiClient('instances', {
    method: 'GET',
    params: {
      typeName: instanceType,
      skip,
      take,
      attributes: ['Name', 'State'],
    },
  });
};

Caveats

• Always define promiseFn functions outside your widget function to avoid infinite re-renders when used with useProtrakApi.
• protrakApiClient requires the user to be authenticated; it reads the auth token from the platform context automatically.
• Use only one of requestConfig or promiseFn in useProtrakApi. If both are passed, requestConfig takes precedence.