Version 1 rules

The rules for the calls in version 1 of the Frantz Public API. The v1 reference has every field of every call. New integrations use version 2: see Moving from v1.

Authentication

Frantz gives you a client API key. Calling Auth/Authorize with it gives you an access token, which you send as apiToken in the body of every other call. The access token is valid for 30 days; after that, call Auth/Authorize again with the API key.

Limits

At most 30 calls to Auth/Authorize a minute from one address, and 3 000 other calls a minute per partner. A call over the limit answers StatusCode 429 in the body, with the seconds to wait in the Retry-After header.

GET api/v1/Auth/Authorize?apiKey={apiKey}

Gives an access token for the client API key. Store the access token on your side and send it with every other call. It is valid for 30 days. After that, authenticate again with the API key.

POST api/v1/Partner/GetPixelScript

Gives the pixel script for a job ad, to be set in the header of its landing page. The script can be stored and inserted into the landing page when it loads. It needs the id of an audience, from GetFrantzSegments.

One job ad, one pixel. Send your own unique reference for the job ad in ProjectReference. The first call for a ProjectReference creates the pixel and returns its feAdId. Every later call with the same ProjectReference and no feAdId updates that pixel with the values you send and returns the same feAdId; it never creates a second pixel. This makes the call safe to repeat, for example after a timeout, and two calls for the same job ad at the same time still give one pixel. Sending feAdId as well updates that pixel directly.

Running a job ad again. Send it again with the same ProjectReference and the new campaignStartDate and campaignEndDate. The statistics and the report continue on the same pixel. If the earlier run has ended and you send no campaignEndDate, the pixel runs for another 21 days, the same as a new pixel.

Addresses. LandingPageUrl, BannerLogoUrl and BannerImageUrl must be whole https addresses. Leave a field out or empty when you have none. A call with another address answers StatusCode 400 and names the field.

POST api/v1/Partner/GetFrantzSegments

Gives the segments for the pixel script request. With a pixel's feAdId, it gives that pixel's segment. Otherwise it gives the segment combinations at the requested level:

• Level 1, industries: only level 1 is filled in.
• Level 2, categories: levels 1 and 2 are filled in, since they are linked to each other. This is the minimum level for the pixel script.
• Level 3, specialities: levels 1, 2 and 3 are filled in for combinations Frantz has set up. For a speciality that is not set up, only level 3 and StyrkKode are filled in, and industry and category are null.

You may show a speciality under a name of your own, as long as you send the four-digit StyrkKode of the original speciality.

POST api/v1/Partner/GetCampaignStatistics

Gives the statistics for a campaign. Call it once a day and save the values with the time you got them. Call it in the morning, some time after 07:00, so the numbers for the day before are included.

It can take several seconds, depending on how much data the campaign has: a campaign on day 4 has less than one on day 14. Do not call it while a user waits. Views and clicks for Meta auto-campaigns are given as Meta stores them. The report URL in the response is the same every time for the same campaign, and shows a simple report with the same numbers.

One row per channel. Each row has channelId, the Frantz campaign channel the traffic came through. It stays the same for the lifetime of the channel, so use it as the key when you store the numbers per day. network names the advertising network the channel runs on: Meta, LinkedIn, BidTheatre, Google, SnapChat, Finn, YouTube, Instagram, TikTok, Twitter or Reddit. Traffic that did not come through a Frantz channel, such as direct traffic, has no channelId and is named by mediaName. Its network is set only when that traffic came from a link on an advertising network.