# Create an inquiry

`POST /fuse/v2/inquiries`

Endpoints:

- `https://api.test.neobits.ai/fuse/v2/inquiries`
- `https://api.prod.neobits.ai/fuse/v2/inquiries`

Authentication: one of the following alternatives:

- `basic`

- `basic`: Basic authentication, base64 encoded username:password.

❗

#### Authorization Required

This endpoint requires authentication via the Core API Auth server.

[Learn about authentication →](https://docs.neobits.ai/api-reference/tag/core-authz.md)

  

If you plan on fetching data that requires prior consent from the user, then you must create an inquiry via this endpoint, and send the user to the inquiry url first. See the `GET /persons/{ssn}` endpoint documentation to see what data you can fetch with/without prior consent from the user.

  

This endpoint returns a link to Neobits' app where Neobits will take the person through the steps necessary to provide their consent and share their data. After the user consents to share their data, they will be redirected to the URL(s) you decide as part of the request body to this endpoint (see request body schema).

  

## Error handling

Errors are attached to the error redirect URL as query parameters. When the user is redirected, the consumer of the API can read the error details to handle it appropriately.

Example error redirect:

```
https://redirect.example.com/error?name=InternalServerError&code=500-001&message=An+internal+server+error+occurred
```

The redirect URL includes three query parameters:

-   **name** - The error type identifier (e.g., `InternalServerError`, `BadRequestError`)
-   **code** - A unique error code in the format `HTTP_STATUS-SEQUENCE`
-   **message** - A URL-encoded human-readable description of the error

📖

#### Complete Error Reference

For a complete list of all possible error codes and their descriptions, see the error documentation.

[View all error codes →](https://docs.neobits.ai/api-reference/errors.md)

## Parameters

| Name | In | Required | Schema | Description |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | no | string; example `7f9c2ba4-e88f-4f2e-9b1d-1f3c6a0e5d21` | Client-chosen key, such as a UUID, that makes a retry safe. A repeated key returns the stored 201 response without running the request again. Reusing a key with a different request returns 409. A non-2xx response does not store the key. |

Parameter definitions (including all schema constraints and serialization options):

```json
[
  {
    "name": "Idempotency-Key",
    "in": "header",
    "required": false,
    "description": "Client-chosen key, such as a UUID, that makes a retry safe. A repeated key returns the stored 201 response without running the request again. Reusing a key with a different request returns 409. A non-2xx response does not store the key.",
    "schema": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    },
    "example": "7f9c2ba4-e88f-4f2e-9b1d-1f3c6a0e5d21"
  }
]
```

## Request body

Required: yes

Content type: `application/json`

```json
{
  "title": "CreateInquiryRequestBody",
  "type": "object",
  "required": [
    "redirect",
    "ssn"
  ],
  "properties": {
    "ssn": {
      "type": "string",
      "example": "01029413157",
      "description": "The unique identifier for the person"
    },
    "externalId": {
      "type": "string",
      "example": "CAN_BE_ANY_STRING",
      "description": "Optional identifier the consumer of the API can provide."
    },
    "skipConsentMessages": {
      "type": "boolean",
      "example": true,
      "description": "Will skip messages explaining to the user which consents are needed to complete the flow."
    },
    "notifications": {
      "type": "array",
      "description": "The notification array allows the consumer of the API to trigger text message and emails to alert the customer",
      "items": {
        "type": "object",
        "title": "NotificationOptions",
        "required": [
          "type",
          "message",
          "to"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "SMS"
            ],
            "example": "SMS"
          },
          "message": {
            "type": "string",
            "example": "Hei. For å dele din informasjon med Bank Bankersen ASA, vennligst gå til denne lenken $link",
            "description": "The consumer of the API can decide where to place the link to initate the process by passing in $link (see example)"
          },
          "to": {
            "type": "string",
            "example": "12345678",
            "description": "The phone number you want the text message to be sent to"
          }
        }
      }
    },
    "redirect": {
      "type": "object",
      "title": "RedirectOptions",
      "description": "URL's provided here will decide where the user should be sent on flow completion",
      "properties": {
        "onSuccess": {
          "type": "string",
          "description": "URL to send the user to after the data is fetched",
          "format": "url",
          "example": "https://your.frontend.com/success"
        },
        "onError": {
          "type": "string",
          "description": "URL to send the user to when an error occurs. See the \"Error handling\" section above for more info.",
          "format": "url",
          "example": "https://your.frontend.com/error"
        }
      }
    }
  }
}
```

## Responses

### 201 Created

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "Location": {
      "description": "The location of the created inquiry in the form of a resource url",
      "schema": {
        "type": "string",
        "format": "url",
        "example": "https://api.test.neobits.ai/fuse/v1/persons/01029413157/inquiries/0679c533-5061-496e-8dc5-df786f04a209"
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "type": "object",
  "title": "Inquiry",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "example": "0679c533-5061-496e-8dc5-df786f04a209"
    },
    "ssn": {
      "type": "string",
      "example": "01029413157",
      "description": "The unique identifier for the person the inquiry is for."
    },
    "url": {
      "example": "https://informasjonsinnhenting.prod.neobits.ai?applicationState=ey12345",
      "format": "uri",
      "type": "string",
      "description": "Give this URL to the user so they can start the flow."
    },
    "externalId": {
      "type": "string",
      "example": "CAN_BE_ANY_STRING",
      "description": "Optional identifier the consumer of the API can provide."
    },
    "skipConsentMessages": {
      "type": "boolean",
      "example": true,
      "description": "Will skip messages explaining to the user which consents are needed to complete the flow."
    },
    "isCompleted": {
      "type": "boolean",
      "example": false,
      "description": "Indicates if the inquiry is completed or not by the user."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-07T15:50:00Z",
      "description": "Inquiry created date"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-07T15:50:00Z",
      "description": "Inquiry last updated date"
    },
    "notifications": {
      "type": "array",
      "description": "The notification options set for the inquiry.",
      "items": {
        "type": "object",
        "title": "NotificationOptions",
        "required": [
          "type",
          "message",
          "to"
        ],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "SMS"
            ],
            "example": "SMS"
          },
          "message": {
            "type": "string",
            "example": "Hei. For å dele din informasjon med Bank Bankersen ASA, vennligst gå til denne lenken $link",
            "description": "The consumer of the API can decide where to place the link to initate the process by passing in $link (see example)"
          },
          "to": {
            "type": "string",
            "example": "12345678",
            "description": "The phone number you want the text message to be sent to"
          }
        }
      }
    },
    "redirect": {
      "type": "object",
      "title": "RedirectOptions",
      "description": "URL's provided here will decide where the user should be sent on flow completion",
      "properties": {
        "onSuccess": {
          "type": "string",
          "description": "URL to send the user to after the data is fetched",
          "format": "url",
          "example": "https://your.frontend.com/success"
        },
        "onError": {
          "type": "string",
          "description": "URL to send the user to when an error occurs. See the \"Error handling\" section above for more info.",
          "format": "url",
          "example": "https://your.frontend.com/error"
        }
      }
    },
    "metadata": {
      "type": "object",
      "properties": {
        "sbl": {
          "type": "object",
          "properties": {
            "authCode": {
              "type": "string",
              "example": "0679c533-5061-496e-8dc5-df786f04a209",
              "description": "Auhtorization code received from Altinn. Used to retrieve the customers data from Skatteetaten."
            }
          }
        }
      }
    },
    "prerequisites": {
      "type": "array",
      "description": "Prerequisites are actions that the user must complete before the data can be fetched. They can either be consents that must be given, or flows that must be completed.",
      "items": {
        "type": "object",
        "title": "Prerequisite",
        "description": "Prerequisites are actions that the user must complete before the data can be fetched. They can either be consents that must be given, or flows that must be completed.",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "SBL"
            ],
            "example": "SBL"
          },
          "isCompleted": {
            "type": "boolean",
            "description": "Whether the prerequisite has been completed or not. When the prerequisite requires the user to give prior consent, this field will be true if the user has given consent."
          },
          "consentUrl": {
            "type": [
              "string",
              "null"
            ],
            "description": "The URL neobits will redirect the user to internally, so the user can complete the prerequisite.",
            "format": "uri"
          }
        }
      }
    }
  }
}
```

### 400 Bad Request

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "BadRequestResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "BadRequest"
            ],
            "example": "BadRequest"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "400-000",
              "400-001",
              "400-002",
              "400-003",
              "400-004",
              "400-005",
              "400-006",
              "400-007",
              "400-008",
              "400-100",
              "400-101",
              "400-102",
              "400-103",
              "400-104",
              "400-105",
              "400-106",
              "400-107",
              "400-108",
              "400-109",
              "400-110",
              "400-111",
              "400-112"
            ],
            "example": "400-001"
          },
          "message": {
            "type": "string",
            "example": "Field 'ssn' is required"
          }
        }
      }
    }
  }
}
```

### 401 Unauthorized

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "UnauthorizedResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "Unauthorized"
            ],
            "example": "Unauthorized"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "401-000",
              "401-001",
              "401-002",
              "401-003",
              "401-004",
              "401-005",
              "401-006",
              "401-007"
            ],
            "example": "401-000"
          },
          "message": {
            "type": "string",
            "example": "Client is not authenticated"
          }
        }
      }
    }
  }
}
```

### 403 Bad Request

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "ForbiddenResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "Forbidden"
            ],
            "example": "Forbidden"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "403-000",
              "403-001"
            ],
            "example": "403-000"
          },
          "message": {
            "type": "string",
            "example": "Client does not have access to this resource"
          }
        }
      }
    }
  }
}
```

### 404 Not Found

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "NotFoundResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "NotFound"
            ],
            "example": "NotFound"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "404-000",
              "404-001",
              "404-002"
            ],
            "example": "404-000"
          },
          "message": {
            "type": "string",
            "example": "The requested resource was not found"
          }
        }
      }
    }
  }
}
```

### 409 Conflict

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "ConflictResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "Conflict"
            ],
            "example": "Conflict"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "409-000",
              "409-001",
              "409-002"
            ],
            "example": "409-000"
          },
          "message": {
            "type": "string",
            "example": "A resource with this identifier already exists"
          }
        }
      }
    }
  }
}
```

### 429 Too Many Requests. When the rate limit rejects a request, the response carries `Retry-After` and only the `errors` field: no `timestamp`, `moreInfo` or `X-Request-ID`, as the request never reached the API.

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "Retry-After": {
      "description": "Seconds to wait before retrying. Sent when the rate limit rejects a request.",
      "schema": {
        "type": "integer",
        "example": 60
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "TooManyRequestsResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "TooManyRequests"
            ],
            "example": "TooManyRequests"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "429-000"
            ],
            "example": "429-000"
          },
          "message": {
            "type": "string",
            "example": "Too many requests. Please try again later."
          }
        }
      }
    }
  }
}
```

### 500 Internal Server Error

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "InternalServerErrorResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "InternalServerError"
            ],
            "example": "InternalServerError"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "500-000",
              "500-001"
            ],
            "example": "500-000"
          },
          "message": {
            "type": "string",
            "example": "An unexpected internal error occurred"
          }
        }
      }
    }
  }
}
```

### 503 Service Unavailable

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "ServiceUnavailableResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "ServiceUnavailable"
            ],
            "example": "ServiceUnavailable"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "503-000"
            ],
            "example": "503-000"
          },
          "message": {
            "type": "string",
            "example": "An error occurred while interacting with a third party service"
          }
        }
      }
    }
  }
}
```

### 504 Gateway Timeout

Response headers and links:

```json
{
  "headers": {
    "Content-Type": {
      "description": "The content type of the response.",
      "example": "application/json; charset=utf-8",
      "schema": {
        "type": "string",
        "enum": [
          "application/json; charset=utf-8"
        ]
      }
    },
    "X-Request-ID": {
      "description": "UUID generated on each request. Provide this id to customer support if an error occurs.",
      "schema": {
        "type": "string",
        "format": "uuid",
        "example": "0679c533-5061-496e-8dc5-df786f04a209"
      }
    }
  }
}
```

Content type: `application/json`

```json
{
  "title": "TimeoutResponse",
  "type": "object",
  "properties": {
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "example": "2019-09-16T22:14:45.624Z"
    },
    "moreInfo": {
      "type": "string",
      "format": "url",
      "example": "https://docs.neobits.ai/"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "enum": [
              "GatewayTimeout"
            ],
            "example": "GatewayTimeout"
          },
          "code": {
            "type": "string",
            "description": "Unique error code in format HTTP_STATUS-SEQUENCE",
            "enum": [
              "504-000"
            ],
            "example": "504-000"
          },
          "message": {
            "type": "string",
            "example": "The request timed out"
          }
        }
      }
    }
  }
}
```