ScoreApp Public API - Getting Started

The ScoreApp Open API lets you connect ScoreApp with external tools and pull Scorecard data programmatically. You can use it to list scorecards, retrieve questions, access category data, and view results and answers.

Important

  • All API requests use Bearer token authentication.
  • The API is rate limited to 100 requests per minute per user/IP.
  • Some data, such as additional_data ,is only available on Pro accounts and requires an email address.

Generate your API

  • Click the ScoreApp logo at the top-left corner.
  • Click Account settings.

  • Click API keys

  • Click add API key and generate your API. You will need this key to authenticate all API requests.

  • Name your API, and click Create secret key

  • Generate a new API key. Copy the key immediately and click Done.

Note: The full API key is only shown once upon creation. If it is not saved at that time, it cannot be retrieved later, you will need to generate a new key.

Open API Endpoints Documentation

The documentation below is a reference of available endpoints, request formats, and response structures. It is not a step-by-step implementation guide.

Authentication

All endpoints require Bearer token authentication using your generated API key.

Authorization: Bearer {token}

Rate Limiting

  • Limit: 100 requests per minute per user/IP
  • Headers: Rate limit information is included in response headers
  • Status Code: 429   when rate limit exceeded

Scorecards

List Scorecards

GET https://open-api.scoreapp.com/scorecards  

Returns a paginated collection of scorecards for the authenticated account.

Parameters

Parameter Type Required Description
limit   integer No Items per page (default: 100)
search   string No Search term for name, key, domain, or account
status   string No Status filter: "draft", "live", "template"
order_by   string No Sort field: "name", "created_at", "updated_at"
order_dir   string No Sort direction: "asc", "desc" (default: "desc")

Example Requests

GET https://open-api.scoreapp.com/scorecards
GET https://open-api.scoreapp.com/scorecards?limit=50&search=customer
GET https://open-api.scoreapp.com/scorecards?status=live
GET https://open-api.scoreapp.com/scorecards?order_by=name&order_dir=asc
GET https://open-api.scoreapp.com/scorecards?search=survey

Response Example

{
  "data": [
    {
      "id": "9e01daab-49c6-428b-9209-b5b0607acad3",
      "name": "Customer Satisfaction Survey",
      "key": "dccdx-8xitgwek",
      "domain": "scoreapp.local",
      "status": "live"
    },
    {
      "id": "7f23bc45-12a8-4d9e-8c7b-3e4f5a6b7c8d",
      "name": "Employee Feedback Form",
      "key": "empfb-9yujhgtr",
      "domain": "scoreapp.local",
      "status": "draft"
    },
    {
      "id": "5a89def2-34c5-4e6f-9a8b-1c2d3e4f5g6h",
      "name": "Product Market Fit Quiz",
      "key": "pmfit-7ikjhgfd",
      "domain": "scoreapp.local",
      "status": "live"
    },
  ],
  "links": {
    "first": "https://open-api.scoreapp.com/scorecards?page=1",
    "last": "https://open-api.scoreapp.com/scorecards?page=10",
    "prev": null,
    "next": "https://open-api.scoreapp.com/scorecards?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://open-api.scoreapp.com/scorecards?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://open-api.scoreapp.com/scorecards?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://open-api.scoreapp.com/scorecards",
    "per_page": 100,
    "to": 100,
    "total": 1000
  }
}

Filter Behavior

  • search: Full-text search across scorecard name, key, domain, and account name
  • status: Filter by scorecard status

Status Values

Value Description
draft   Draft Mode
live   Live/Complete
template   Template

Status Codes

Code Description
200   Success
401   Unauthorized
422   Validation Error (invalid parameters)
429   Rate limit exceeded

Get Scorecard Questions

GET https://open-api.scoreapp.com/scorecards/{scorecard}/questions  

Returns all main questions for a scorecard with their options and categories.

Parameters:

  • scorecard   (string, required) - The scorecard ID

Response Example:

{
  "data": [
    {
      "id": "4751e041-3ba1-4017-9554-23bfab6ecc4d",
      "type": "quiz",
      "question": "How satisfied are you with our customer service?",
      "answer_type": "yesno",
      "order": 1,
      "required": true,
      "categories": [
        {
          "id": "62338872-848a-4032-8027-2b659e614d85",
          "title": "Customer Service",
          "order": 1,
          "type": "visible",
          "scoring_logic": "add",
          "deleted_at": null
        }
      ],
      "options": [
        {
          "option": "Yes",
          "option_value": null,
          "order": 1,
          "type": "regular"
        },
        {
          "option": "No",
          "option_value": null,
          "order": 2,
          "type": "regular"
        }
      ]
    },
    {
      "id": "a0f14224-7d61-437f-8851-54bff7923720",
      "type": "quiz",
      "question": "What could we improve about our product?",
      "answer_type": "text",
      "order": 2,
      "required": false,
      "categories": [],
      "options": []
    },
    {
      "id": "b1e25335-8e72-448g-9962-65cgg8834e9f",
      "type": "signup",
      "question": "What is your email address?",
      "answer_type": "text",
      "order": 3,
      "required": true,
      "categories": [],
      "options": []
    }
  ]
}

Status Codes:

  • 200   - Success
  • 401   - Unauthorized
  • 404   - Scorecard not found

Get Scorecard Categories

GET https://open-api.scoreapp.com/scorecards/{scorecard}/categories  

Returns all categories for a scorecard with their associated images.

Parameters:

  • scorecard   (string, required) - The scorecard ID

Response Example:

{
  "data": [
    {
      "id": "62338872-848a-4032-8027-2b659e614d85",
      "title": "Customer Service",
      "order": 1,
      "type": "visible",
      "scoring_logic": "add"
    },
    {
      "id": "848e0858-12f4-4992-a90c-0c15f4051d54",
      "title": "Product Quality",
      "order": 2,
      "type": "hidden",
      "scoring_logic": "add"
    },
    {
      "id": "b6b51383-1ba1-46ab-ada6-845b9f6d75b3",
      "title": "User Experience",
      "order": 3,
      "type": "visible",
      "scoring_logic": "add"
    }
  ]
}

Status Codes:

  • 200   - Success
  • 401   - Unauthorized
  • 404   - Scorecard not found

Notes:

  • Returns all categories (both visible and hidden types)
  • Returns empty array if no categories exist
  • scoring_logic  : "add" = Add to total score, "none" = No effect on total score
  • type  : "visible" or "hidden"

Results

List Results

GET https://open-api.scoreapp.com/scorecards/{scorecard}/results  

Returns a paginated collection of results (leads) for a specific scorecard.

Parameters:

  • scorecard   (integer, required) - The scorecard ID
  • limit   (integer, optional) - Number of items per page (default: 100, max: 100)
  • search   (string, optional) - Search term for filtering results by "first_name", "last_name", "email"
  • start_date   (string, optional) - Start date filter (ISO UTC DateTime format)
  • end_date   (string, optional) - End date filter (ISO UTC DateTime format)
  • status   (string, optional) - Result status filter: "started" or "finished"
  • response_count   (string, optional) - Filter by response count: "single" or "multiple"
  • order_by   (string, optional) - Field to order by: "first_name", "last_name", "email", "created_at", "id"
  • order_dir   (string, optional) - Order direction: "asc" or "desc" (default: "desc")

Example URLs:

GET https://open-api.scoreapp.com/scorecards/1/results
GET https://open-api.scoreapp.com/scorecards/1/results?limit=50&search=john
GET https://open-api.scoreapp.com/scorecards/1/results?start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z
GET https://open-api.scoreapp.com/scorecards/1/results?status=finished&response_count=single

Response Example:

{
  "data": [
    {
      "id": "2756c677-1820-438f-b7b1-a4669d126eb2",
      "key": "68e4b88db87ac413480498",
      "purchased": true,
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "status": "finished",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "60c518b7-3569-460c-b66f-cf405f283bc6",
      "key": "68e4b531da6eb421197299",
      "purchased": false,
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "status": "started",
      "created_at": "2024-01-15T09:15:00.000Z"
    }
  ],
  "links": {
    "first": "https://open-api.scoreapp.com/scorecards/1/results?page=1",
    "last": "https://open-api.scoreapp.com/scorecards/1/results?page=5",
    "prev": null,
    "next": "https://open-api.scoreapp.com/scorecards/1/results?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "https://open-api.scoreapp.com/scorecards/1/results?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "https://open-api.scoreapp.com/scorecards/1/results?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": null,
        "label": "Next »",
        "active": false
      }
    ],
    "path": "https://open-api.scoreapp.com/scorecards/1/results",
    "per_page": 100,
    "to": 100,
    "total": 500
  }
}

Status Values:

  • started   - Quiz was started but not completed
  • finished   - Quiz was completed successfully

Status Codes:

  • 200   - Success
  • 401   - Unauthorized
  • 404   - Scorecard not found
  • 422   - Validation Error (invalid parameters)

Show Result

GET https://open-api.scoreapp.com/scorecards/{scorecard}/results/{result}  

Returns a single result with optional includes.

Parameters:

  • scorecard   (integer, required) - The scorecard ID
  • result   (integer, required) - The result ID
  • include[]   (array, optional) - Array of relationships to include

Available Includes:

  • answers   - Include question answers
  • scores   - Include calculated scores
  • source   - Include source information
  • activity   - Include activity log
  • additional_data   - Include enriched contact data (Pro accounts only, requires email)

Example URLs:

GET /api/scorecards/1/results/123
GET /api/scorecards/1/results/123?include[]=answers
GET /api/scorecards/1/results/123?include[]=scores
GET /api/scorecards/1/results/123?include[]=answers&include[]=scores&include[]=source
GET /api/scorecards/1/results/123?include[]=answers&include[]=scores&include[]=source&include[]=activity

Response Example (without includes):

{
  "data": {
    "id": "2756c677-1820-438f-b7b1-a4669d126eb2",
    "key": "68e4b88db87ac413480498",
    "purchased": true,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "status": "finished",
    "created_at": "2024-01-15T14:25:00.000Z"
  }
}

Response Example (with all includes):

{
  "data": {
    "id": "2756c677-1820-438f-b7b1-a4669d126eb2",
    "key": "68e4b88db87ac413480498",
    "purchased": true,
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "status": "finished",
    "created_at": "2024-01-15T14:25:00.000Z",
    "answers": [
      {
        "id": "a0f14224-7d61-437f-8851-54bff7923720",
        "type": "multiple_choice",
        "question": "What's your biggest marketing challenge?",
        "answer_type": "single_choice",
        "order": 1,
        "required": true,
        "categories": [
          {
            "id": "62338872-848a-4032-8027-2b659e614d85",
            "title": "Marketing Strategy",
            "order": 1,
            "type": "visible",
            "scoring_logic": "add"
          }
        ],
        "options": [
          {
            "option": "Lead Generation",
            "option_value": "3",
            "order": 1,
            "type": "regular"
          },
          {
            "option": "Content Creation",
            "option_value": "2",
            "order": 2,
            "type": "regular"
          }
        ],
        "answers": [
          {
            "id": 1234,
            "option_id": 567,
            "question_id": "a0f14224-7d61-437f-8851-54bff7923720",
            "answer": "Lead Generation",
            "score": 3.0,
            "asked_order": 1,
            "time_spent": 4200,
            "score_potential": 3.0,
            "created_at": "2024-01-15T14:26:00.000Z"
          }
        ],
        "deleted_at": null
      }
    ],
    "scores": [
      {
        "type": "total",
        "category": null,
        "score_potential": "15.00",
        "score": "12.50",
        "score_percent": "83.33",
        "score_count": "5.00"
      },
      {
        "type": "category",
        "category": {
          "id": "62338872-848a-4032-8027-2b659e614d85",
          "title": "Marketing Strategy",
          "order": 1,
          "type": "visible",
          "scoring_logic": "add"
        },
        "score_potential": "9.00",
        "score": "7.00",
        "score_percent": "77.78",
        "score_count": "3.00"
      }
    ],
    "source": {
      "utm_source": "facebook",
      "utm_campaign": "spring_promo_2024",
      "utm_medium": "social",
      "utm_term": "marketing_quiz",
      "utm_content": "carousel_ad"
    },
    "activity": [
      {
        "action": "finished",
        "created_at": "2024-01-15T14:32:15.000Z"
      },
      {
        "action": "results",
        "created_at": "2024-01-15T14:32:15.000Z",
        "page": {
          "title": "Your Marketing Score Results",
          "slug": "https://mysite.com/quiz-results",
          "is_default_page": false,
          "status": "published",
          "type": "result-page"
        }
      },
      {
        "action": "answered",
        "created_at": "2024-01-15T14:31:45.000Z"
      },
      {
        "action": "started",
        "created_at": "2024-01-15T14:28:30.000Z"
      }
    ],
    "additional_data": [
      {
        "key": "contactFirstName",
        "value": "John"
      },
      {
        "key": "contactLastName",
        "value": "Doe"
      },
      {
        "key": "contactJobTitle",
        "value": "Software Engineer"
      },
      {
        "key": "companyDomain",
        "value": "example.com"
      }
    ]
  }
}

Status Codes:

  • 200   - Success
  • 401   - Unauthorized
  • 404   - Scorecard or result not found
  • 422   - Validation Error (invalid parameters)

Get Result Answers

GET https://open-api.scoreapp.com/scorecards/{scorecard}/results/{result}/answers  

Returns question answers for a specific result.

Parameters:

  • scorecard   (integer, required) - The scorecard ID
  • result   (integer, required) - The result ID

Response Example:

{
  "data": [
    {
      "id": "a0f14224-7d61-437f-8851-54bff7923720",
      "type": "multiple_choice",
      "question": "What's your biggest marketing challenge?",
      "answer_type": "single_choice",
      "order": 1,
      "required": true,
      "categories": [
        {
          "id": "62338872-848a-4032-8027-2b659e614d85",
          "title": "Marketing Strategy",
          "order": 1,
          "type": "visible",
          "scoring_logic": "add",
          "deleted_at": null
        }
      ],
      "options": [
        {
          "option": "Lead Generation",
          "option_value": "3",
          "order": 1,
          "type": "regular"
        },
        {
          "option": "Content Creation",
          "option_value": "2",
          "order": 2,
          "type": "regular"
        }
      ],
      "answers": [
        {
          "answer": "Yes",
          "option": {
            "option": "Yes",
            "option_value": null,
            "order": 1,
            "type": "regular"
          },
          "score": "3.00",
          "time_spent": 4200
        }
      ],
      "deleted_at": null
    },
    {
      "id": "a0f14224-7d61-437f-8851-54bff7923720",
      "type": "quiz",
      "question": "What could we improve about our product?",
      "answer_type": "text",
      "order": 2,
      "required": false,
      "categories": [],
      "options": [],
      "answers": [
        {
          "answer": "Better user interface and faster loading times",
          "option": null,
          "score": null,
          "time_spent": 8500
        }
      ],
      "deleted_at": null
    }
  ]
}

Status Codes:

  • 200   - Success
  • 401   - Unauthorized
  • 403   - Forbidden (Pro accounts only, requires email)
  • 404   - Scorecard or result not found

Still need help? Contact Us Contact Us