Hämta data till ditt Business Intelligence (BI)-system

I den här artikeln går vi igenom hur du kan använda vårt API för att hämta respondenter, bakgrundsdata och svar till ditt Business Intelligence-system (BI).

Integration via InSurveys API

InSurvey erbjuder ett omfattande API som gör det möjligt att utföra alla åtgärder som är tillgängliga i gränssnittet, även programmatiskt. För att förenkla integrationer med Business Intelligence-system (BI) finns två särskilda API-endpoints framtagna för detta ändamål. Den fullständiga API-dokumentationen finns här: https://api.insurvey.com.

Steg 1: Servicekonto och behörigheter

Vi rekommenderar att du skapar ett (eller flera) dedikerade InSurvey-konton som enbart används för integrationer. Här kan du läsa mer om olika användartyper och hur du skapar ett nytt konto. Om du inte har tillgång till Användare och team, eller om din organisation använder en särskild inloggningslösning (till exempel Single Sign-On), kontakta i första hand din organisations systemägare, så hjälper de dig vidare.

När servicekontot är skapat behöver kontot få tillgång till de formulär ni vill hämta data från. Som standard har en användare i InSurvey endast åtkomst till formulär som denne själv har skapat. En användare som har behörighet till formuläret behöver därmed dela ut formuläret till servicekontot. Läs mer om hur du ger en användare behörighet till ett formulär här.

Om servicekonto inte finns i listan över användare, kontakta i första hand din organisations systemägare, så hjälper de dig vidare.

Steg 2: Logga in

För att kunna anropa API:et behöver du först hämta en giltig "åtkomsttoken" (token). Token erhålls genom att logga in via API:ets inloggningsendpoint. Vid inloggningen (och alla efterföljande anrop) behöver du inkludera vissa HTTP-headers. Samtliga anrop måste innehålla headern X-Forward-Host, som anger vilken organisation som gör API-anropet.

Exempel: Om din InSurvey-adress är http://alloy.insurvey.com ska följande header anges:

X-Forward-Host: alloy.insurvey.com

Anrop

POST /auth/login HTTP/1.1
Host: api.insurvey.com
X-Forward-Host: alloy.insurvey.com
Content-Type: application/json
{
  "email": "ditt_service_konto@organisation.se",
  "password": "ditt_service_kontos_lösenord"
}

Svar

{
  "token": "13;915C6B6A-F362-45E9-874D-56DB7F223B74",
  "id": 13,
  "firstname": "Service",
  "lastname": "Konto"
  // Övriga egenskaper borttagna för ökad läsbarhet
}

En tokens giltighet

När ett servicekonto loggar in skapas en ny token, och alla tidigare genererade tokens blir då ogiltiga. Det innebär att ett servicekonto endast kan ha en aktiv inloggning åt gången. Om ni till exempel har två integrationsjobb som kör parallellt behöver dessa antingen:

dela samma token, eller
använda två separata servicekonton.

En token är giltig i 24 timmar, vilket innebär att du inte behöver logga in inför varje API-anrop. Det räcker att logga in en gång per dygn för att hämta en ny token.

Steg 3: Hämta definitioner

När du har fått din token kan du börja anropa API:ets övriga endpoints. För att anropen ska accepteras behöver du inkludera följande två HTTP-headers i varje anrop:

X-Forward-Host: alloy.insurvey.com
X-Auth-Token: <din token>

När du hämtar definitionerna behöver du dessutom ange ID-numret för den aktuella fältperioden. Du hittar detta ID i gränssnittet genom att öppna Distribution och datainsamling, gå till den aktuella fältperioden och klicka på Inställningar – under Detaljer visas fältperiodens ID-nummer.

Anrop

GET /bi/powerBi/{fieldPeriodId}/definition?cultureAlias=sv-SE&fallbackToMasterCulture=false HTTP/1.1
Host: api.insurvey.com
X-Forward-Host: alloy.insurvey.com
X-Auth-Token: 13;915C6B6A-F362-45E9-874D-56DB7F223B74

Tips! Om formuläret är översatt till flera språk kan du hämta formulärdefinitionen för ett specifikt språk genom att ange parameter ?cultureAlias= följt av språkkoden. Exempel: ?cultureAlias=sv-SE returnerar formulärdefinitionen på svenska.

Svar

Svaret innehåller detaljerad information om formulärets frågor och vilka bakgrundsdatafält som finns tillgängliga.

{
    "id": 143,
    "name": "Mitt formulär",
    "form": [ // Formuläret och dess innehåll
        {
            "uri": "is://form.tree/2271:2294/14798:14384/",
            "type": "Option",
            "name": "Hur trivs du på jobbet?",
            "alternatives": [
                {
                    "id": 33503,
                    "uri": "is://form.tree/2271:2294/14798:14384/?alternativeId=33503",
                    "name": "Bra"
                },
                {
                    "id": 33504,
                    "uri": "is://form.tree/2271:2294/14798:14384/?alternativeId=33504",
                    "name": "Dåligt"
                }
            ],
            "isMandatory": false,
            "min": "1",
            "max": "1",
            "isPersonalData": false
        }
    ],
    "responderDataMetadata": [ // Bakgrundsdata för respondenterna
        {
            "id": 209,
            "name": "E-post",
            "isPersonalData": true
        }
    ]
}

Steg 4: Hämta bakgrundsdata och svar

När du har hämtat formulärdefinitionen kan du gå vidare och hämta de faktiska respondenterna, deras bakgrundsdata samt svar.

Anrop

GET /bi/powerBi/{fieldPeriodId}/responders?page=1&pageSize=1024&cultureAlias=sv-SE&fallbackToMasterCulture=false&includePersonalData=true HTTP/1.1
Host: api.insurvey.com
X-Forward-Host: alloy.insurvey.com
X-Auth-Token: 13;915C6B6A-F362-45E9-874D-56DB7F223B74

Tips! För att svaret inte ska bli för stort kan du som mest hämta 1024 respondenter åt gången. Om din undersökning innehåller fler respondenter behöver du hämta resterande data genom att paginera – det vill säga anropa nästa ”sida” genom att öka värdet på parametern page till 2, 3, 4 och så vidare.

I InSurvey kan administratörer markera vilka frågor och bakgrundsdatafält som innehåller personuppgifter. Om du vill utesluta dessa fält i ditt API-svar kan du sätta följande parameter: ?includePersonalData=false

Svar

Svaret innehåller en lista över respondenter med deras svar och bakgrundsdata. Genom att koppla ihop denna information med formulärdefinitionen kan du tolka vilka svar som hör till respektive fråga och vilket bakgrundsdata som tillhör varje respondent.

{
    "totalNbrOfItems": 999, // Totalt antal respondenter
    "items": [ // Respondenterna
        {
            "id": 101597,
            "guid": "f5e2c20a-64ee-4931-b770-9612f8c0eeb0",
            "formAnswerSegmentGuid": "c6d04c0f-4aa6-4c74-a1e2-d5cef130e088",
            "answers": [ // Respondentens svar
                {
                    "guid": "c7166c44-f973-45e3-beb5-94ca8081d586",
                    "segmentGuid": "c6d04c0f-4aa6-4c74-a1e2-d5cef130e088",
                    "contentInstanceUri": "is://form.tree/2271:2294/14798:14384/",
                    "uri": "is://form.tree/2271:2294/14798:14384/",
                    "alternativeId": 33503,
                    "alternativeUri": "is://form.tree/2271:2294/14798:14384/?alternativeId=33503",
                    "valueString": "Bra"
                }
            ],
            "responderData": [ // Respondentens bakgrundsdata
                {
                    "id": 209,
                    "value": "sundberg.morgongåva.19991@mortex.se",
                    "isPersonalData": true
                }
            ],
            "state": "Finished",
            "lastUsedAt": "2025-11-05T07:47:58.090Z",
            "finishedAt": "2025-11-05T07:47:58.090Z"
        }
    ]
}

Begränsningar

Denna endpoint är begränsad till att hämta de 20 000 första respondenterna. Om du försöker hämta fler än 20 000 respondenter returnerar API:et följande felmeddelande.

HTTP 400 Bad Request
{
    "type":"SearchQueryResultWindowsToLargeException",
    "httpStatusCode":"BadRequest",
    "statusCode":"400 BadRequest",
    "message":"ResultWindowTooLarge"
}