GoliathDevelopersGet an API key
Guides / Account API

Account API

Read and update your profile and organization settings, route new contacts, inspect permissions, and manage integration connections through the Goliath developer API

About

Read the key owner’s profile, organization role, timezones, and permissions; update profile details; and inspect or disconnect integrations. Profile and mailbox reads use the key owner’s account; shared integrations use the key’s organization. Connecting integrations requires a human’s login in the app.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

Reading your account (READ scope)

operationId What it does
getIntegrationSetupUrls In-app settings page URLs where a human connects an email account (Google/Microsoft) or sets up Twilio phone numbers for calling/SMS. Send the user the matching link to complete these flows in the app.
getMyProfile Fetch the key owner’s identity, profilePictureUrl, organizationRole, organizationMembershipStatus, timezone, resolvedTimezone, and organization id/name/timezone. Use it to read current values before updateMyProfile and check the owner’s role before an ADMIN operation.
getMyCapabilities The key owner’s own permissions — the capabilities they hold. The nine capabilities are VIEW_ALL_CONTACTS, VIEW_ALL_DEALS, VIEW_ALL_PHONES, CONTRACTS_VIEW, CONTRACTS_MANAGE, CAN_SKIPTRACE, CAN_EXPORT, CAN_WORKFLOW, and VIEW_TEAM_DIRECTORY. Team admins hold all nine. A missing capability is not held; an empty list means none are held, while a null list means the lookup failed and says nothing.

organizationRole is ADMIN or MEMBER; membership status is ACTIVE or SUSPENDED. Use resolvedTimezone when interpreting times for the key owner. A null personal or organization timezone means none was chosen, not UTC; the resolved value applies the availability-schedule and organization fallbacks.

For MEMBER seats, the three VIEW_ALL_* capabilities and CONTRACTS_VIEW/CONTRACTS_MANAGE are opt-in. The contract capabilities govern viewing and managing contracts wherever the contract surface enforces them; their presence does not add contract operations to this API. CAN_SKIPTRACE, CAN_EXPORT, and CAN_WORKFLOW are on unless revoked. VIEW_TEAM_DIRECTORY controls whether teammate identities are visible. Independent-operator seats lack it and have fixed role permissions that cannot be granted individually.

Writing your account (WRITE scope)

operationId What it does
setMyTimezone Set or clear (timezone: null) the key owner’s own time zone. resolvedTimezone then falls back to the availability schedule and the organization.
updateMyProfile Update the key owner’s own profile. firstName, lastName, and phoneNumber are required together — send current values for fields you aren’t changing. An empty phoneNumber clears it; otherwise it is normalized and must be unique. Optional profilePictureUrl (HTTPS) and howDidYouHearAboutUs (free text) leave stored values untouched when omitted. Email is not editable. Returns the updated identity and profilePictureUrl.

Integrations (ADMIN scope)

operationId What it does
listIntegrations Read connection status for the key owner’s mailboxes and Facebook Lead Ads, the organization’s Slack and dialers (CallTools, smrtPhone, Enzo, ReadyMode), direct-mail connections, and phone-enrichment providers. Enzo and ReadyMode include linked campaigns. Zapier, incoming webhooks, and API keys are not listed.
disconnectSlack Disconnect the organization’s Slack workspace; Slack notifications stop.
disconnectCallTools Revoke the CallTools key and the webhook automations Goliath created there; dispositions stop syncing.
disconnectSmrtPhone Disconnect the organization’s smrtPhone dialer; its calls stop syncing.
disconnectDialer Disconnect provider: ENZO or READYMODE, including every linked campaign.
disconnectFacebookLeadAds Disconnect the key owner’s Facebook account. Goliath’s access is removed; Page unsubscription and Facebook deauthorization are best-effort. Inspect pagesDisconnected and deauthorized; if deauthorization failed, remove the app in Facebook settings.
disconnectDirectMail Disconnect one connectionId from listIntegrations. New workflow mail sends through it are refused; mail already submitted to the provider is not cancelled.
disconnectPhoneEnrichmentProvider Disconnect a providerKey from phoneEnrichmentQuery.providers[].provider.key and return its new connectionStatus.

Facebook Lead Ads is connected only when a returned Page has connected: true; facebookAccountConnected alone means the account is signed in. A null Page list means Facebook did not answer. Direct-mail connections report state and authHealth; phone-enrichment providers report connectionStatus.

Organization settings (READ + ADMIN scopes)

operationId Scope What it does
getOrganizationSettings READ The organization’s profile and org-wide settings in one read: name, slug, website, time zone, the National DNC text skip, the AI line head start, the text-reply and call line policies, the inbox default view, the suggestion audience, the outbound pause, and lead routing. Read it before changing any of the settings below.
renameOrganization ADMIN Rename the organization. The name is carried into the AI employees’ instructions and the onboarding drip.
setOrganizationSlug ADMIN Set the booking-link slug. The old slug keeps resolving.
setOrganizationTimezone ADMIN Set or clear (null) the organization’s own time zone.
setOrganizationTextDncSkip ADMIN Turn “always skip National DNC numbers when texting” on or off (alwaysExcludeDncTexts).
setOrganizationAiLineHeadStart ADMIN Seconds a person sharing a line with an AI employee gets to reply before the AI does; null clears it.
setOrganizationTextReplyLinePolicy ADMIN Which line a contact’s text composer opens on: USER_PRIMARY_LINE or LAST_THREAD_LINE.
setOrganizationCallLinePolicy ADMIN Which line a manual dial defaults to: ASK_BEFORE_DIALING, USER_PRIMARY_LINE, or LAST_CALL_LINE.
setOrganizationInboxDefaultView ADMIN What the inbox shows before a person chooses: INDIVIDUAL or TEAM.
setOrganizationLeadRouting ADMIN Who gets new skip-traced leads: one assigneeUserIds entry for one person, several for an even split, [] for nobody.
setOrganizationOutboundPause ADMIN “Pause everything”: paused: true stops every automated outbound message (workflow texts and emails, AI employee texts, emails, and calls, drips, mail, and developer-API sends) until it is turned off. Queued work waits; nothing is cancelled. A person’s own sends in the app still go out. false resumes.
setSuggestionAudience ADMIN Set who contact suggestion cards go to: WHOLE_TEAM or POINT_PERSON.

setMyTimezone (WRITE) sets or clears the key owner’s own time zone; the organization’s is setOrganizationTimezone.

Areas of operation

operationId Scope What it does
getOrganizationAreasOfOperation READ The organization’s markets: county, city, or ZIP regions and drawn polygons. Null until set.
updateOrganizationAreasOfOperation ADMIN Replace the areas of operation with { version: 1, regions, polygons, updatedAt }. A region is a county (fips from searchCounties), a city (cityId from searchCities), or a ZIP. This is a full replacement: read the current value first and send everything back.

Intake assignment (who gets new contacts)

An intake assignment decides who owns the contacts that inbound traffic creates: the people (several rotate), participants, teams, tags, AI employees attached, and workflows fired. Each owner has its own: owner is { kind, id } with kind one of ORG (the organization default), LINE (a phone line), META_PAGE (a Facebook Page), or WORKFLOW (an event workflow). The organization default is read with getPhoneRouting on the Communications API.

operationId Scope What it does
getLineIntakeAssignments READ Each phone line’s own intake assignment; null when the line follows the organization default.
getMetaPageIntakeAssignments ADMIN Each Facebook Page’s own intake assignment, through the key owner’s own Facebook sign-in; null for a Page nobody configured. Returns [] when the key owner has not connected Facebook, which does not mean no Page is routed.
getWorkflowIntakeAssignment READ One event workflow’s (workflowGroupId) intake assignment; null when it has none.
setIntakeAssignment ADMIN Replace an owner’s whole assignment: assigneeUserIds (in order; two or more rotate), participantUserIds, teamIds, tags, agentAssigneeIds, workflowGroupIds. A WORKFLOW owner takes no AI employees or workflows (send both as []).
clearIntakeAssignment ADMIN Delete an owner’s assignment for good. A line then falls back to the organization default; clearing ORG deletes the default itself, so a line without its own assigns nobody.

Direct mail (READ scope)

operationId What it does
listDirectMailLetters The letters on contacts you can see (Automations → Letters), newest first: totalCount, then a page (limit defaults to 50, offset) with contact, campaign, workflow, mode (LIVE, or TEST, which mails and bills nothing), status (QUEUED, SUBMITTED, MAILED, IN_TRANSIT, DELIVERED, RETURNED, CANCELED, FAILED, …), and the requested, mailed, and delivered dates. Narrow with statuses, modes, or search (a contact or workflow name). totalCount: 0 with no filters means no letter on a visible contact was mailed.

Example

Read the current profile:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "getMyProfile", "variables": {} }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.