Graveinfo.Kobler gravere og infrastruktureiere

Send din første gravemelding via API

Fra null til sendt gravemelding på under 10 minutter. Denne guiden er for entreprenører som vil integrere gravemeldingssending i eget system.

Forutsetninger

  • ✓Du har en Graveinfo-konto.
  • ✓Kontoen er koblet til en registrert entreprenørprofil.
  • ✓Du har koordinater for arbeidsområdet i WGS84 (lengdegrad/breddegrad), slik de kommer fra GPS, Google Maps og de fleste GIS-verktøy.
1

Skaff en API-nøkkel med riktige scopes

Gå til Dashboard → API-nøkler på entreprenørprofilen og opprett en ny nøkkel. Du trenger scopet gravemeldinger:write for å opprette og sende, og gravemeldinger:read for å hente status og svar etterpå.

Viktig: Nøkkelen tilhører entreprenørprofilen som opprettet den, og alle gravemeldinger sendes på dens vegne. Nøkkelen vises kun én gang. Lagre den i en miljøvariabel:

export GRAVEINFO_API_KEY="gv_live_..."
2

Tegn arbeidsområdet som et polygon i WGS84

Arbeidsområdet sendes som et GeoJSON-polygon i EPSG:4326 (WGS84) med koordinater i rekkefølgen [lengdegrad, breddegrad]. Det er samme format som GPS, Google Maps og de fleste GIS-verktøy gir deg. Du trenger ikke konvertere til UTM - Graveinfo gjør det selv.

json
{
  "type": "Polygon",
  "coordinates": [[
    [10.7522, 59.9139],
    [10.7535, 59.9139],
    [10.7535, 59.9150],
    [10.7522, 59.9150],
    [10.7522, 59.9139]
  ]]
}

Polygon-krav: Polygonet må være en lukket ring - siste koordinat må være lik den første. Koordinatene skal angi yttergrensen av arbeidsområdet. Kommunen utledes automatisk fra polygonet, så du trenger ikke oppgi kommunenummer. For Norge ligger lengdegrad typisk mellom 4 og 31 og breddegrad mellom 58 og 71 - får du verdier i hundretusener er koordinatene i UTM og må gjøres om først.

3

Opprett gravemeldingen med POST /api/v1/gravemeldinger

Send en POST-forespørsel med tittel, polygon, planlagt periode, arbeidstyper og kontaktperson. Graveinfo oppretter gravemeldingen som et utkast og finner ledningseierne som dekker polygonet - ingen varsler sendes ennå:

bash
curl -X POST "https://graveinfo.no/api/v1/gravemeldinger" \
  -H "Authorization: Bearer $GRAVEINFO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Graving Storgata 12",
    "description": "Legging av fiberkabel langs Storgata 12-18",
    "workTypes": ["telekommunikasjon", "grunnarbeid"],
    "location": {
      "type": "Polygon",
      "coordinates": [[
        [10.7522, 59.9139],
        [10.7535, 59.9139],
        [10.7535, 59.9150],
        [10.7522, 59.9150],
        [10.7522, 59.9139]
      ]]
    },
    "plannedStart": "2026-10-01",
    "plannedEnd": "2026-10-14",
    "contactPerson": {
      "name": "Ola Nordmann",
      "phone": "91234567"
    }
  }'

Et vellykket kall returnerer HTTP 201 med utkastet og mottakerlisten:

json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "referenceNumber": "GI-2026-00042",
  "status": "draft",
  "recipients": [
    {
      "organizationId": "7cb5ab12-8901-4de5-b3fc-1a234d56e78f",
      "name": "Elvia AS",
      "status": "pending"
    },
    {
      "organizationId": "9ab12cd3-4567-8ef9-a0bc-1d234e56f78a",
      "name": "Oslo kommune VAV",
      "status": "pending"
    }
  ],
  "createdAt": "2026-09-15T10:00:00.000Z",
  "_links": {
    "self": "/api/v1/gravemeldinger/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "send": "/api/v1/gravemeldinger/3fa85f64-5717-4562-b3fc-2c963f66afa6/send"
  }
}
idGravemeldingens ID. Du trenger den for å sende og for å hente status.
referenceNumberReferansenummeret du bruker i all videre kommunikasjon med mottakere og Graveinfo.
statusAlltid "draft" her. Ingenting er sendt før du kaller /send.
recipientsLedningseierne Graveinfo fant for polygonet. Sjekk at listen ser riktig ut. Er den tom, vil /send feile med NO_RECIPIENTS_FOUND.
_links.sendStien du kaller for å sende gravemeldingen (neste steg).

Gyldige verdier i workTypes: telekommunikasjon, vann_avlop, hoyspenning, lavspenning, veiarbeid, grunnarbeid, fjernvarme, annet, pressing, boring. plannedStart må være dagens dato eller senere, og plannedEnd samme dag som eller etter plannedStart.

4

Send gravemeldingen

Når mottakerlisten ser riktig ut, send gravemeldingen med POST /api/v1/gravemeldinger/{id}/send. Kallet har ingen kropp. Graveinfo varsler ledningseierne, setter frister og endrer status fra draft til sent:

bash
GRAVEMELDING_ID=3fa85f64-5717-4562-b3fc-2c963f66afa6

curl -X POST "https://graveinfo.no/api/v1/gravemeldinger/$GRAVEMELDING_ID/send" \
  -H "Authorization: Bearer $GRAVEINFO_API_KEY"

Svaret er HTTP 200 med sendetidspunkt, mottakere og resultatet av hvert e-postvarsel:

json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "referenceNumber": "GI-2026-00042",
  "status": "sent",
  "sentAt": "2026-09-15T10:00:01.000Z",
  "recipients": [
    {
      "organizationId": "7cb5ab12-8901-4de5-b3fc-1a234d56e78f",
      "name": "Elvia AS",
      "status": "pending"
    },
    {
      "organizationId": "9ab12cd3-4567-8ef9-a0bc-1d234e56f78a",
      "name": "Oslo kommune VAV",
      "status": "pending"
    }
  ],
  "emailResults": [
    { "recipientId": "a1b2c3d4-5678-90ab-cdef-1234567890ab", "success": true },
    { "recipientId": "b2c3d4e5-6789-01bc-def1-234567890abc", "success": true }
  ],
  "_links": {
    "self": "/api/v1/gravemeldinger/3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

emailResults viser om e-postvarselet til hver mottaker gikk gjennom. Mottakere som har gravemottak via et eksternt skjema får ikke e-post og er ikke med i listen. Et utkast kan bare sendes én gang - et nytt kall gir HTTP 409 INVALID_STATUS.

Alternativ - autoSend: Vil du sende umiddelbart uten å inspisere mottakerlisten, sett "autoSend": true i opprettelseskallet i steg 3. Da får du /send-svaret over direkte, med HTTP 201 og status: "sent". Feiler sendingen, returneres utkastet med et _warnings-felt (kode AUTO_SEND_FAILED) - da finnes utkastet, og du kan kalle /send på nytt.

5

Følg med på status og svar fra mottakerne

Bruk ID-en til å hente oppdatert status med GET /api/v1/gravemeldinger/{id} (scope gravemeldinger:read):

bash
# Hent oppdatert status og svar fra mottakerne
curl "https://graveinfo.no/api/v1/gravemeldinger/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $GRAVEINFO_API_KEY"
json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "referenceNumber": "GI-2026-00042",
  "status": "sent",
  "title": "Graving Storgata 12",
  "location": { "type": "Polygon", "coordinates": [[ ... ]] },
  "plannedStart": "2026-10-01",
  "plannedEnd": "2026-10-14",
  "createdAt": "2026-09-15T10:00:00.000Z",
  "sentAt": "2026-09-15T10:00:01.000Z",
  "recipients": [
    {
      "organizationId": "7cb5ab12-8901-4de5-b3fc-1a234d56e78f",
      "name": "Elvia AS",
      "status": "responded",
      "response": "no_conflict",
      "responseNote": "Ingen kabler i dette området.",
      "respondedAt": "2026-09-15T14:30:00.000Z",
      "hasKartblad": true,
      "kartbladUrl": "https://storage.graveinfo.no/kartblad/...?signature=..."
    },
    {
      "organizationId": "9ab12cd3-4567-8ef9-a0bc-1d234e56f78a",
      "name": "Oslo kommune VAV",
      "status": "pending",
      "response": null,
      "responseNote": null,
      "respondedAt": null,
      "hasKartblad": false,
      "kartbladUrl": null
    }
  ],
  "summary": {
    "total": 2,
    "responded": 1,
    "pending": 1,
    "hasConflicts": false
  }
}
statusdraft (ikke sendt), sent (sendt, venter på svar), in_progress (alle har svart, eller saken venter på kommunen) eller completed (klar eller arkivert).
recipients[].responseno_conflict: ingen infrastruktur i området. conflict: mottakeren har infrastruktur i området - ta kontakt før du graver. needs_meeting: mottakeren trenger befaring eller mer informasjon. null til mottakeren har svart.
responseNoteFritekst fra mottakeren, for eksempel kontaktinfo eller hva du må ta hensyn til.
hasKartbladOm mottakeren har lastet opp kartblad. Da inneholder kartbladUrl en signert nedlastingslenke som er gyldig i én time - hent gravemeldingen på nytt for en ny lenke.
summarytotal, responded og pending teller mottakere. hasConflicts er true når minst én mottaker har svart conflict.

Endepunktet har ingen rate limit, men svarene kommer over dager, ikke sekunder - poll med god margin:

typescript
async function pollUntilAllResponded(gravemeldingId: string): Promise<void> {
  while (true) {
    const res = await fetch(`https://graveinfo.no/api/v1/gravemeldinger/${gravemeldingId}`, {
      headers: { Authorization: `Bearer ${process.env.GRAVEINFO_API_KEY}` },
    });
    const data = await res.json();

    if (data.summary.pending === 0) {
      const conflicts = data.recipients.filter((r: { response: string | null }) => r.response === 'conflict');
      console.log(`Alle har svart. ${conflicts.length} konflikter.`);
      return;
    }

    console.log(`${data.summary.responded}/${data.summary.total} har svart`);
    await new Promise((r) => setTimeout(r, 15 * 60_000)); // vent 15 minutter
  }
}

Se API-referansen for alle felt, og for GET /api/v1/gravemeldinger som lister alle gravemeldingene dine med filter på status og dato.

Feilsøking

VALIDATION_ERRORHTTP 400 - ett eller flere felt er ugyldige eller mangler

Løsning: Objektet error.fields inneholder én melding per felt, for eksempel { "plannedStart": "Må være i fremtiden" } eller { "location.coordinates": "Required" }. Typiske årsaker: koordinater som ikke er tall, plannedStart ligger i fortid, workTypes er tom eller inneholder en ukjent verdi, eller contactPerson mangler name/phone.

NO_MUNICIPALITIES_FOUNDHTTP 400 - polygonet treffer ingen norsk kommune

Løsning: Nesten alltid feil koordinatsystem eller feil rekkefølge. Koordinatene skal være [lengdegrad, breddegrad] i WGS84 - for Norge omtrent [10.75, 59.91], ikke [59.91, 10.75]. Verdier i hundretusener (f.eks. 258000, 6648000) er UTM og må gjøres om til WGS84 før du sender.

NO_RECIPIENTS_FOUNDHTTP 400 fra /send - ingen ledningseiere i området

Løsning: Utkastet ble opprettet, men Graveinfo fant ingen ledningseiere som dekker polygonet, så det kan ikke sendes. Bruk GET /api/v1/coverage?municipality=XXXX for å sjekke hvilke eiere som er registrert i kommunen. Kontakt oss hvis eiere mangler.

INSUFFICIENT_SCOPEHTTP 403 - nøkkelen mangler gravemeldinger:write

Løsning: Scopes settes når nøkkelen opprettes og kan ikke endres etterpå. Opprett en ny nøkkel med gravemeldinger:write (og gravemeldinger:read) i dashbordet.

MISSING_CONTRACTORHTTP 403 - nøkkelen er ikke koblet til en entreprenørprofil

Løsning: Gravemelding-endepunktene krever en nøkkel som tilhører, eller deler organisasjonsnummer med, en registrert entreprenør. En nøkkel opprettet på en ledningseier-organisasjon uten entreprenørprofil fungerer ikke her. Opprett nøkkelen fra entreprenørprofilen i dashbordet.

INVALID_STATUSHTTP 409 - gravemeldingen er allerede sendt

Løsning: /send kan bare kalles én gang per gravemelding. Fikk du timeout på et tidligere kall, hent gravemeldingen med GET /api/v1/gravemeldinger/{id} og sjekk om status allerede er "sent" i stedet for å sende på nytt.

Rate limits: POST /gravemeldinger tillater 10 kall per minutt og /send 5 kall per minutt per nøkkel. Ved overskridelse svarer API-et med HTTP 429.

Klar for full API-dokumentasjon?

Se API-referansen →