Who needs this: every FrequencyOS account that wants its contact data to sync completely into HighLevel. Takes about 3 minutes, once per sub-account.

Why this extra step exists

When you connect HighLevel with the normal "Connect" button, you're using OAuth. OAuth lets FrequencyOS read and write contacts, notes, tags and opportunities — that covers most of the sync.

What OAuth cannot do is create custom fields. HighLevel deliberately withholds that permission from OAuth apps. FrequencyOS stores about 20 pieces of information per contact that HighLevel has no built-in home for — things like where a lead originally came from, their domain portfolio bucket, last real conversation date, and content engagement signals. Those live in custom fields named fos_*.

If you've ever seen a sync finish with "couldn't prepare custom fields" or "not_authorized", this is why. A Private Integration Token (PIT) fixes it permanently.

Step 1 — Create the token in HighLevel

  1. Open your HighLevel sub-account (not the agency view).
  2. Go to Settings → Business Profile → Private Integrations.
  3. Click Create new Integration.
  4. Name it FrequencyOS so you recognise it later.
  5. Tick exactly these three scopes:
    • View Locations (locations.readonly)
    • View Custom Fields (locations/customFields.readonly)
    • Edit Custom Fields (locations/customFields.write)
  6. Click Create, then copy the token. HighLevel shows it once — if you lose it, delete the integration and make a new one.

Only tick the three scopes above. Extra permissions don't help and widen the blast radius if the token is ever leaked.

Step 2 — Paste it into FrequencyOS

  1. In FrequencyOS go to Dashboard → Integrations.
  2. Find the Advanced Access card (key icon).
  3. Click Add token, paste the token, and save.

FrequencyOS immediately calls HighLevel to check it. When it works you'll see:

  • The Location ID of the sub-account it resolved to
  • Verified less than a minute ago
  • Three scope chips: locations.readonly, locations/customFields.readonly, locations/customFields.write

The token is encrypted at rest and is never sent back to your browser. Nobody — including FrequencyOS staff — reads it out of the dashboard.

Step 3 — Create the custom fields

Verifying the token does not create the fields. That's one more click:

  1. Go to Contacts → HighLevel fields.
  2. Click Create missing fields.
  3. You'll get a summary: N already existed · N created · N couldn't be created.

That's it. You do not need to re-run a full contact sync just to get the fields — the field-creation step is separate. Once the fields exist, your normal Push to HL runs will start filling them in.

If anything shows as failed, the same screen lists the exact field name, key and type so you can add it by hand in HighLevel → Settings → Custom Fields. Use the key exactly as shown or the sync won't find it.

Troubleshooting

"HighLevel rejected the token" — the token was copied with a trailing space, or the integration was created at the agency level instead of the sub-account. Recreate it inside the sub-account.

Token saved but scopes are missing — you'll see an amber "limited" state. Go back into the HighLevel integration and tick the missing scope, then use Replace token in FrequencyOS with a fresh token.

Wrong Location ID shown — the token belongs to a different sub-account. Delete it and generate one from the correct location.

Rotating or revoking — deleting the private integration inside HighLevel instantly kills the token. Use Replace token in FrequencyOS to swap in the new one; nothing else in your setup needs to change.

Do I have to give my token to FrequencyOS support? No. That's the entire point of this card — you add it yourself, once, and the system takes over from there.

  • Import contacts into FrequencyOS — clean and load your list before you sync
  • Contacts → HighLevel fields — the live reference for all 20 fos_* fields