Job adverts and ConnectID

A job advert is one job ad in your system, as you send it to Frantz. Frantz gives it a ConnectID and a script for its page, and counts its visitors under that ConnectID.

All of them need the scope job-adverts:write. GET /api/v2/audiences also takes campaigns:read, for partners that only order campaigns.

Two ids

• externalReference is your id for the job ad, up to 50 characters. It is unique among your job adverts, and Frantz compares it without regard to case: AD-1 and ad-1 are the same job advert.
• connectId is the ConnectID Frantz gives the job advert. It is the id in the addresses, in the script and in Frantz' reports.

Store both. Send your reference when you send the job advert, and use the ConnectID for everything else.

Sending a job advert

POST /api/v2/job-adverts needs externalReference and landingPageUrl. The rest is optional.

• A new reference creates the job advert and answers 201 Created, with its address in Location.
• A reference you already have updates that job advert with the fields you send and answers 200 OK. It never makes a second job advert, not even when two calls for the same reference arrive at the same time.

So the call is safe to repeat. If it times out, send it again.

POST /api/v2/job-adverts HTTP/1.1
Host: api.frantz.no
Authorization: Bearer fzat_...
Content-Type: application/json

{
  "externalReference": "ad-12345",
  "landingPageUrl": "https://jobs.example.com/ad-12345",
  "title": "Nurse, Haukeland",
  "startDate": "2026-10-20",
  "endDate": "2026-11-30",
  "applicationDueDate": "2026-11-15",
  "styrk": 2223
}

Fields

The response has all of these, and also connectId, script, reportUrl (the Frantz report for the job advert), createdDate and updatedDate.

Changing a job advert

Send the new values with PATCH /api/v2/job-adverts/{connectId}, or send the job advert again with POST. Both follow the same rules:

• A field you leave out, or send as null, stays as it is.
• An empty string ("") clears a text field.

PATCH /api/v2/job-adverts/744376 HTTP/1.1
Host: api.frantz.no
Authorization: Bearer fzat_...
Content-Type: application/json

{
  "applicationDueDate": "2026-11-22",
  "bannerShortText": ""
}

A ConnectID that is not yours answers 404, the same as one that does not exist.

Running a job ad again

To run a job ad again, send it again with POST and the same externalReference, with the new startDate and endDate. It keeps its ConnectID, and the statistics go on from where they were. If its end date has passed and you send no new one, it runs for another 21 days.

PATCH changes only what you send, so it does not start an ended job advert again by itself.

Finding a job advert

GET /api/v2/job-adverts?externalReference=ad-12345 gives a list with the job advert, or an empty list when you have none with that reference. GET /api/v2/job-adverts/{connectId} gives one job advert, or 404.

{
  "items": [
    {
      "connectId": 744376,
      "externalReference": "ad-12345",
      "script": "<script crossorigin='anonymous' async='' data-r='744376' data-frpixel='744376' src='https://...'></script>",
      "title": "Nurse, Haukeland",
      "landingPageUrl": "https://jobs.example.com/ad-12345",
      "startDate": "2026-10-20",
      "endDate": "2026-11-30",
      "applicationDueDate": "2026-11-15",
      "audienceId": 1421,
      "styrk": 2223,
      "reportUrl": "https://...",
      "createdDate": "2026-10-19T08:15:02Z",
      "updatedDate": "2026-10-19T08:15:02Z"
    }
  ]
}

The script

script is the tag that measures the job ad's visitors. Put it at the end of <head> on the page in landingPageUrl, one per page.

• Use the value as it is. Do not build the tag yourself from the ConnectID. Frantz may change the script's address and attributes, and every response with the job advert has the current tag.
• Store it with the job ad, and replace it whenever a response gives you a new one.
• It asks for consent. The script follows the page's consent tool, or shows Frantz' own notice when the page has none. For a visitor who does not consent to marketing cookies, it stores and sends nothing, and the visit is not counted.

Audiences

An audience tells Frantz who the job ad is for. Audiences have three levels: industry, category and speciality. A job advert should have one at category level or below. There are three ways to choose it:

• By STYRK code: send styrk without audienceId, and Frantz picks the audience whose speciality has that code.
• From a job title: GET /api/v2/audiences?title=Sykepleier gives the audiences that fit, best first. It can be none or several: Frantz does not guess, so choose one.
• From the list: GET /api/v2/audiences?level=category gives every audience at that level, and GET /api/v2/audiences gives them all.

{
  "items": [
    {
      "audienceId": 1421,
      "level": "speciality",
      "industry": { "name": "Helse og omsorg", "reach": 310000 },
      "category": { "name": "Sykepleie", "reach": 120000 },
      "speciality": { "name": "Sykepleier", "reach": 85000 },
      "styrk": 2223
    }
  ]
}

reach is roughly how many potential candidates each level reaches. A speciality Frantz has not linked to a category comes back without industry and category, with its STYRK code. Give the audience to the job advert as audienceId.