Kom i gang

Oversikt⁠

Med Attia-API-et kan dine egne programmer lese data fra et arbeidsområde, og opprette stillinger i det, over HTTPS. Alle adresser starter med https://attia.app/api/v1, alle svar er JSON, og en personlig API-nøkkel viser hvem du er.

Versjon 1 har sju operasjoner foreløpig: List opp stillinger, Hent en stilling, Opprett en stilling, List opp søknader, Hent en søknad, List opp kandidater og Hent en kandidat. Denne siden tar deg fra ingen nøkkel til ditt første svar.

API-et er tilgjengelig på Business og Enterprise. På andre planer forklarer Innstillinger → API hva API-et gjør i stedet for å vise innstillingene. En administrator får Oppgrader til Business der, og alle andre en linje som ber dem spørre en administrator i arbeidsområdet om å oppgradere. Når arbeidsområdet fortsatt har webhooks eller API-nøkler, ser en administrator også en linje med antallene, og hvert antall lenker til sin liste.

Opprett en nøkkel⁠

Åpne Innstillinger → Sikkerhet og tilgang → Personlige API-nøkler og velg Ny API-nøkkel. Gi nøkkelen et navn og minst tillatelsen Lese. Attia viser nøkkelen én gang, så kopier den da. En nøkkel starter med attia_api_.

Nøkkelen handler som deg. Den kan gjøre det du selv kan gjøre i arbeidsområdet, og ikke mer enn tillatelsene og teamene du ga den. Autentisering dekker tillatelser, tilbakekalling og IP-begrensninger.

Send nøkkelen⁠

Send nøkkelen i Authorization-headeren som et bearer-token.

curl https://attia.app/api/v1/jobs \  -H "Authorization: Bearer $ATTIA_API_KEY"

Kall API-et fra en server eller et skript, aldri fra en nettside. API-et sender ingen CORS-headere, så nettleseren avviser svaret, og en nøkkel i kildekoden til en side kan hvem som helst kopiere.

Din første forespørsel⁠

Legg nøkkelen i en miljøvariabel og be om to stillinger.

export ATTIA_API_KEY="attia_api_..." curl "https://attia.app/api/v1/jobs?limit=2" \  -H "Authorization: Bearer $ATTIA_API_KEY"

En liste svarer med data og next_cursor.

{  "data": [    {      "id": "0192f3a1-6b02-7d4c-8e11-5a9c0b7d3e01",      "title": "Backend-utvikler",      "slug": "backend-utvikler",      "status": "live",      "team_id": "0192f39f-11aa-7c3e-b2d4-9e8f7a6b5c4d",      "employment_type": "full_time",      "contract_type": "permanent",      "workplace_type": "hybrid",      "locations": ["Eksempelvik"],      "positions_count": 2,      "application_deadline": "2026-11-15",      "published_at": "2026-09-28T07:30:00.000000Z",      "closed_at": null,      "archived_at": null,      "created_at": "2026-09-25T12:04:51.220417Z",      "updated_at": "2026-10-01T09:42:10.118305Z"    },    {      "id": "0192f3a1-7c44-7b1e-9a50-3f1d2c6e8a02",      "title": "Butikksjef",      "slug": "butikksjef",      "status": "draft",      "team_id": "0192f39f-11aa-7c3e-b2d4-9e8f7a6b5c4d",      "employment_type": "part_time",      "contract_type": "temporary",      "workplace_type": "onsite",      "locations": [],      "positions_count": 1,      "application_deadline": null,      "published_at": null,      "closed_at": null,      "archived_at": null,      "created_at": "2026-10-02T08:15:30.482913Z",      "updated_at": "2026-10-02T08:15:30.482913Z"    }  ],  "next_cursor": "eyJ1IjoiMjAyNi0xMC0wMlQwODoxNTozMC40ODI5MTNaIiwiaSI6IjAxOTJmM2ExLTdjNDQtN2IxZS05YTUwLTNmMWQyYzZlOGEwMiJ9"}

next_cursor er ikke null, så det finnes flere stillinger. Paginering viser hvordan du henter dem.

Webhooks⁠

En webhook sender en POST til URL-en din når noe skjer i arbeidsområdet. Webhooks følger med API-et, på Business og Enterprise. En administrator i arbeidsområdet setter opp hver av dem med et navn, en URL, hendelsene den følger og, om de vil, ett team. Se Sett opp en webhook. Et verktøy som Zapier kan også abonnere og avslutte abonnementet gjennom API-et, med nøkkelen til en administrator: se Webhooks.

Versjon 1 sender åtte hendelser:

• job.created: en stilling ble opprettet.
• job.updated: et felt API-et returnerer for en stilling, ble endret, eller en slettet stilling ble gjenopprettet.
• job.deleted: en stilling ble slettet.
• application.created: en søknad ble opprettet.
• application.status_changed: en søknad ble flyttet til en annen status.
• application.updated: et felt API-et returnerer for en søknad, ble endret, eller en slettet søknad ble gjenopprettet.
• application.deleted: en søknad ble slettet.
• candidate.erased: en kandidat ble slettet for godt fra arbeidsområdet.

Hver endring sender én hendelse, med postens public_revision som revision. En flytting til en annen status sender application.status_changed, og den sender også application.updated bare når den samme endringen berører et annet felt, for eksempel hvem søknaden er tildelt. En endring i et felt API-et ikke returnerer, sender ingenting, men den kan likevel flytte public_revision, så revisjonsnumre kan hoppe over tall. En stilling eller søknad som flyttes til et annet team, sender hendelsen til webhooks på det nye teamet, ikke det gamle.

Søknadshendelser sendes bare mens en administrator har slått på Kandidatdata i API-et under Innstillinger → API. Mens bryteren er av, sender Attia ingen, og når den slås på igjen, sendes ikke de som ble hoppet over. candidate.erased sendes uansett, fordi den bare har kandidatens id, så du kan slette kopien din. En kandidat hører ikke til noe team, så candidate.erased går til alle webhooker som følger den, også en webhook satt til ett team. Har du aldri sett den kandidaten, kan du se bort fra id-en.

En webhook handler som administratoren som satte den opp. Attia sjekker tilgangen til administratoren når den sender, så en stilling eller søknad administratoren ikke lenger kan se, blir ikke sendt. En webhook slås av når administratoren forlater arbeidsområdet eller ikke lenger er administrator, eller etter 24 timer med mislykkede leveranser. Når administratoren har forlatt arbeidsområdet eller ikke lenger er administrator, handler webhooken deretter som administratoren som slår den på igjen.

Sett opp en webhook⁠

En administrator setter opp en webhook under Innstillinger → API. Under Webhooks velger du Ny webhook, eller + når listen allerede har en, og fyller ut skjemaet:

• Navn: navnet på webhooken i listen.
• URL: adressen Attia sender hver hendelse til. Den må starte med https://.
• Signeringshemmelighet: Attia lager den for deg. Bruk den til å sjekke signaturen.
• Hendelser ved dataendring: Søknader, Kandidater og Stillinger. Søknader er krysset av fra start. Hver boks følger alle hendelsene av sin type, og Kandidater er candidate.erased. Vil du følge enkelthendelser, abonnerer du gjennom API-et.
• Valg av team: Alle offentlige team eller ett team. Du kan ikke endre dette etter opprettelsen. Alle offentlige team utelater private team, så et privat team trenger sin egen webhook.

Velg Opprett webhook, så åpner Attia siden til webhooken. Der ser du leveringsstatusen og leveringsfeilene, og du kan når som helst kopiere hemmeligheten eller bytte den. Tredotsmenyen der, og på raden til webhooken i listen, har Rediger webhook for navn, URL og hendelser, Deaktiver webhook eller Aktiver webhook, og Slett webhook.

Etter en nedgradering under Business blir webhooken stående. Siden til en webhook som er på, viser Satt på pause: plan, og Attia sender ingenting før arbeidsområdet er tilbake på Business eller Enterprise. Attia sender ikke hendelsene den hoppet over. For å åpne eller slette en webhook etter en nedgradering følger en administrator webhook-antallet under Oppgrader til Business i Innstillinger → API. Ny webhook vises ikke der før arbeidsområdet er tilbake på Business eller Enterprise.

Forespørselen⁠

Brødteksten er JSON.

{  "id": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",  "type": "job.created",  "version": "v1",  "timestamp": "2026-10-02T08:15:31.004127Z",  "workspace_id": "0192f39e-02b1-7a5c-9d3e-4f6a8b0c2d1e",  "revision": 1,  "data": {    "id": "0192f3a1-7c44-7b1e-9a50-3f1d2c6e8a02",    "title": "Store manager",    "slug": "store-manager",    "status": "draft",    "team_id": "0192f39f-11aa-7c3e-b2d4-9e8f7a6b5c4d",    "employment_type": "part_time",    "contract_type": "temporary",    "workplace_type": "onsite",    "locations": [],    "positions_count": 1,    "application_deadline": null,    "published_at": null,    "closed_at": null,    "archived_at": null,    "created_at": "2026-10-02T08:15:30.482913Z",    "updated_at": "2026-10-02T08:15:30.482913Z"  }}

• id er leveransens id, samme verdi som headeren webhook-id.
• type er hendelsen.
• version er API-versjonen data følger: v1.
• timestamp er når endringen skjedde. Den er lik ved hvert nytt forsøk; headeren webhook-timestamp har tidspunktet for forsøket.
• revision er revisjonen posten hadde da hendelsen skjedde, så du kan ordne to hendelser for samme post. Den er null på candidate.erased.
• data er stillingen eller søknaden slik GET /api/v1/jobs/{id} eller GET /api/v1/applications/{id} gir den til administratoren når Attia sender. Den kan være nyere enn hendelsen. På job.deleted, application.deleted og candidate.erased har data bare id.
• previous finnes bare på job.updated og application.updated. Det har de gamle verdiene til feltene hendelsen endret, og ingen andre felt, for eksempel {"title": "Butikkleder"}. Verdiene er slik de var da hendelsen skjedde, i samme format som data, så previous.title er tittelen før denne endringen selv om data er nyere. Et felt data ikke returnerer, er ikke med. En gjenoppretting har ikke previous, og det har heller ikke en hendelse fra før feltet fantes. En flytting til en annen status holder current_status_id, board_category og withdrawn_at utenfor previous, fordi application.status_changed melder den flyttingen. Attia lagrer de gamle verdiene sammen med hendelsen og tømmer dem når kandidaten slettes for godt.

Tre headere bærer signaturen: webhook-id, webhook-timestamp og webhook-signature. Forespørselen har også content-type: application/json og user-agent: Attia-Webhooks/1.0.

Sjekk signaturen⁠

Attia signerer etter Standard Webhooks. webhook-signature er v1, og så base64 av HMAC-SHA256 over <webhook-id>.<webhook-timestamp>.<brødtekst>, med bytene etter whsec_ i hemmeligheten din som nøkkel. I 24 timer etter at en hemmelighet er byttet, har headeren to signaturer skilt med et mellomrom, og forespørselen er ekte hvis én av dem stemmer. Alle Standard Webhooks-biblioteker sjekker dette for deg, og avviser et tidsstempel som er mer enn fem minutter fra klokka di.

Svar og nye forsøk⁠

Svar med en 2xx-status innen 5 sekunder. Etter 408, 429, 5xx, tidsavbrudd eller ingen forbindelse prøver Attia igjen med samme webhook-id: 1 minutt etter det første forsøket, 1 time etter det andre og så hver 6. time, i opptil 24 timer. Stopper en Attia-prosess midt i en leveranse, kan neste forsøk komme tidligere. Feiler leveransen fortsatt etter 24 timer, slår Attia av webhooken, avbryter leveransene som står i kø, og sier fra til alle administratorer på e-post og i innboksen. En administrator slår den på igjen under Innstillinger → API. Der står det hvorfor webhooken er av, og siden til webhooken viser leveransene som feilet de siste 90 dagene. Hendelser Attia hoppet over mens webhooken var av, sendes ikke senere. Alle andre statuser, også en omdirigering, avslutter leveransen. En brødtekst over 256 KB sendes aldri.

Levering skjer minst én gang, så samme webhook-id kan komme to ganger. Hopp over en id du allerede har behandlet.

En administrator kan levere én mislykket leveranse på nytt om gangen fra siden til webhooken under Innstillinger → API, så lenge webhooken er på og i opptil 30 dager etter at leveransen feilet. Leveransen beholder samme webhook-id og id, så hopp over den hvis du allerede har behandlet den id-en. Attia leser data på nytt med tilgangen administratoren av webhooken har da. Leveransen forsvinner fra listen når den er levert, og blir stående med det nye resultatet hvis den feiler igjen.

Neste steg⁠

• Autentisering: nøkkelformatet, tillatelser, tilbakekalling og IP-begrensninger.
• Paginering: sidestørrelse, cursorer, henting av endringer, og hvordan tidsstempler, null og enum-verdier ser ut.
• Feil: problemdokumentet og alle feilkodene.
• Rategrenser: hvor mange forespørsler du kan sende, og headerne som teller dem.
• Versjonering: hva som kan endre seg i versjon 1, og hvordan en utfasing varsles.
• Stillinger: alle parametere og felt i GET /api/v1/jobs og GET /api/v1/jobs/{id}.
• Søknader: alle parametere og felt i GET /api/v1/applications og GET /api/v1/applications/{id}.
• Kandidater: alle parametere og felt i GET /api/v1/candidates og GET /api/v1/candidates/{id}, og bryteren de trenger.
• Webhooks: abonner med POST /api/v1/webhooks, avslutt abonnementet med DELETE /api/v1/webhooks/{id} og les eksempelhendelser med GET /api/v1/webhooks/samples/{event}, slik Zapier gjør, og list opp webhooks med GET /api/v1/webhooks.