> ## Documentation Index > Fetch the complete documentation index at: https://docs.birdeye.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Survey > Create Survey API helps create a new survey for the required question structure and further displays it on the survey list page. Please go through this document for a detailed explanation of request body fields ## OpenAPI ````yaml api/openapi.yaml POST /v1/survey/external/create/{businessId} openapi: 3.0.0 info: title: Birdeye version: 0.0.1 description: >- Birdeye helps businesses grow through happy customers. Over 80,000 businesses use Birdeye everyday to attract new leads with Listings, Reviews and Referrals, convert them into customers with Webchat, Appointments, and Payments, and delight those customers with Surveys, Ticketing, and Insights - all in one place. The Birdeye APIs are built on HTTP and are RESTful APIs. * Uses resource-oriented URLs. * Uses built-in HTTP capabilities for passing parameters and authentication. * Responds with standard HTTP response codes to indicate errors. * Requests and responses payload attached with all the mentioned APIs, you may choose your preferred language per the integration requirement. ### Authentication and Rate limiting > __NOTE:__ > - __All API requests targeting business accounts must include the x-api-key header. This header is required and mandatory for successful authentication and access to the API endpoints.__ > > - __To protect your API key and prevent unauthorized access, please ensure all API requests are made from your backend server. Do not call the APIs directly from the browser or expose your API key in any client-side code.__ To call a Birdeye API, you need a valid API key. It can be fetched via the Birdeye dashboard and is a confidential key. There is a limit to calling APIs with each API key [connect with the support team to get the current limit]. If too many requests are made within the threshold timeframe, an error will be returned in the response. ### Pagination Multiple API supporting pagination. These APIs have two parameters sindex and count. * sindex: is the start index * count: No. of records, you want to fetch. > __Note__ > - _Deep Pagination with record window greater than 100k is not supported. Either reduce the sindex + count to be less than equal to 100k or use appropriate filters to narrow down your result set._ For example : * Suppose you have to fetch 20 records: 


    API call 1 -> sindex=0, count 10

    API call 2 -> sindex -> 10, count 10.
* To fetch 100kth record: 


    sindex = 99000 and count = 1000

    will just work fine as sindex + count = 100000 which is less than 100,000.
* If you fetch more than 100kth records: 


    sindex = 99000 and count = 1001, sindex + count = 100001

    which is greater than 100,000. Thus, you'll receive an error in response.
### HTTP Status Codes Every API response will have an HTTP status code. * 200 - OK: API request is successful * 202 - Accepted: The API request has been accepted for processing. * 400 - Bad Request: The API request was unacceptable, often due to a missing or invalid parameter. * 404 - Not Found: The requested resource does not exist. * 429 - Rate Limited: You have made too many requests within the threshold timeframe. * 500 - Internal Server Error: Something went wrong on our end. Please get in touch with support. ### Error Response Birdeye API will return a validation error in case of missing/invalid input in the request. The response will return the errorCode and errorMessage. For example : 


    {
        "code": 1161,
        "message": "Invalid API key"
    }
servers: - url: https://api.birdeye.com/resources security: [] tags: - name: Business description: Create and maintain your business on Birdeye. - name: Custom Fields description: Create, delete , update , associate and get custom fields easily. - name: User description: Delete and manage user profiles and permissions easily. - name: Reviews description: Consistently generate more reviews and higher ratings. - name: Contact description: >- Manage contacts across locations effortlessly with a robust Contact Management System. - name: Contact V2 description: >- Easily manage contacts across multiple locations using enhanced Contact APIs, featuring built-in support for communication preference flags. - name: Campaign description: >- Create a short link for review requests and set review sources in the template. - name: Aggregation description: Access your public data from 150+ review sites. - name: Report description: >- Various reporting data points across Birdeye modules like reviews, insights and competitors etc for all your data visualisation - name: Survey description: >- Engage each customer at the right time with NPS or CSAT surveys to improve your service. - name: Business Media description: >- Add, delete and manage business media. > __Supported Media Size__ > - _Photo: JPG or PNG. 720 x 720px. 10KB min._ > - _Video: 30 sec long. 720p or more upto 75MB._ > __Note__ > - _Uploaded media will be pushed to your google business profile (if connected) and other long tail directories only._ - name: Social description: Create and track Social posting for all channels. - name: Employee - name: Conversation description: >- Connect with customers across a range of digital channels from one unified inbox. - name: Subscription description: >- Subscribe or Unsubscribe multiple webhooks with different URLs or Events for a subscription and deliver real-time notifications. - name: Webhook description: >- Configure multiple webhooks with different URLs for a subscription and deliver real-time notifications. - name: Competitor description: Make competitive insights your unfair advantage. - name: Competitor AI description: Competitive intelligence, simplified by AI. - name: Insight AI description: Insight intelligence, simplified by AI. - name: Google Q&A description: >- > __Note__ > - _Applicable to be used only by paid listings clients, for their active locations, for the Google Q&A section, in the Google listing_ - name: Google Services description: >- > __Note__ > - _Applicable to be used only by paid listings clients, for their active locations, for the Google Services section, in the Google listing._ > - _No two services should have the same service name. It is recommended that all services created should HAVE UNIQUE service names._ > - _You CAN have the same service across two diff categories e.g.: Emergency counselling as a $100 paid service can be a service created & mapped to category A - Mental health and category B - Psychotherapy - both categories being present for the same location._ - name: FAQ description: >- To retrieve all Question and Answer (QnA) entries across locations using FAQ APIs, enabling smart support and knowledge features for businesses. - name: Listing description: >- Keep your business information accurate and consistent across 50+ websites. - name: GMB Products description: >- To manage products, locations, and business details through Listing GMB platform - name: Search AI description: >- Search AI provides a comprehensive view of your business performance across AI-powered search platforms, including data accuracy, sentiment analysis, citations, brand ranking, and overall visibility. - name: Ticketing description: >- Create standout customer support with ticketing across reviews, untagged, and survey responses. - name: Integration description: Birdeye integrates with various software or tools you use. - name: Change Logs description: >- * 07/03/2026 - Updated `mainBusinessDescription` and microsite `internalListing.description` fields in Create, Update and Get Listing APIs to be optional instead of required, with support for clearing the existing value by sending an empty string (V2BIRD-1690). * 06/10/2026 - Updated Get Contact API to support an optional `experienceScore` boolean field in the request body (default: false). When set to true, the response includes the customer's experience score and source. * 05/25/2026 - Added Update Custom card (PUT) and Delete Custom card (DELETE) API documentation under the Business profile custom card section. * 05/11/2026 - Added support for backdated survey responses in the POST Survey Response API. The `created` field (UTC Epoch milliseconds) is optional; if omitted, the server defaults to the current UTC timestamp. * 04/22/2026 - Provide subLocality field support in Get, Create and Update Listings APIs for NZ Locations. * 04/16/2026 - Added Archived Get Reviews API under Reviews group. * 04/06/2026 - Updated Get Reviews API documentation to improve clarity on review statuses and how to retrieve all review types. * 03/24/2026 - Added Social Open URL Performance Report API and Insight AI APIs to retrieve location-wise metrics and benchmark score. * 03/18/2026 - Added Create Custom Card Time API under custom fields section. * 03/03/2026 - Added Response Time (overtime & by-location) and Response Rate(overtime & by-location) APIs under reports section and created group for Competitor AI. * 03/02/2026 - Added sendInvite (boolean, default - true) field in Create User Signup v2 API request body and attributes. * 02/11/2026 - Updated the API key identifier for applicable APIs by moving it from a query parameter to the x-api-key request header. * 02/03/2026 - Added the "Get All QnA" API under FAQ group to enable retrieval of QnA entries across business locations, with full request and response documentation * 01/19/2026 - Added a note under the Authentication and Rate limiting section specifying that the x-api-key header is mandatory for all API requests targeting EU region business accounts. * 01/13/2026 - Added Create User (Signup) API under User module to create and invite users for a business. * 09/22/2025 - Added GMB Products APIs to onboard/connect Google Merchant accounts and manage product listing actions. * 08/21/2025 - Added Single main business description Support. * 08/19/2025 - Added competitor /raptor public APIs for reviews aggregates. * 06/26/2025 - Added Contact V2 APIs with communication preference flag support. * 12/13/2024 - Added inline reply support for GetReviews APIs. * 09/27/2024 - Added update for Google Opening Soon (BIRD-56987) * 06/25/2024 - Updated Listings Insights API (BIRDEYE-137367) * 05/29/2024 - Added Google Q&A Developers API Section * 05/13/2024 - Added epoc date support for GetReviews APIs. * 03/22/2024 - Add Update Hierarchy API (BIRD-32609) * 03/19/2024 - Added Ticket APIs Create, Get, Update APIs under Ticket module * 02/26/2024 - Updated logoUrl description in Get, Update APIs under Business module and Create, Get, Update APIs under Listing module (BIRD-29386) * 12/21/2023 - Add listing phase 2 api changes (BIRD-16589) * 11/08/2023 - Add survey changes (BIRD-11944) and listing changes (BIRD-14345) * 11/08/2023 - Added CRUD APIs for Apple chat * 10/15/2023 - Added CRUD APIs for Business Media. * 10/11/2023 - Added new APIs under Listing module, Create, Update, Get, Deactive Listings * 09/18/2023 - Added new API under Contact module i.e, Get opt-out contact data * 08/25/2023 - Added new APIs under Business and Listing modules, Get Category List API, Get GMB Attributes API & Get Timezone List * 07/21/2023 - Added new API under Business module i.e, Business Search API. * 06/30/2023 - Added support for service area based information in Get Business API and Update Business API. * 10/04/2024 - Added support to fetch ticketId associated with the survey responses in List Response API. paths: /v1/survey/external/create/{businessId}: post: tags: - Survey summary: Create Survey description: >- Create Survey API helps create a new survey for the required question structure and further displays it on the survey list page. Please go through this document for a detailed explanation of request body fields operationId: createSurvey parameters: - name: businessId in: path description: Id of the Business. required: true example: '12345678' schema: type: string - name: Accept in: header description: e.g. application/json required: false example: application/json schema: type: string default: application/json - name: x-api-key in: header description: >- e.g. [Required] Partner specific API key provided by Birdeye for data exchange. required: false example: >- [Required] Partner specific API key provided by Birdeye for data exchange. schema: type: string - name: Content-Type in: header description: Media type of the JSON request body. required: false example: application/json schema: type: string default: application/json requestBody: content: application/json: schema: type: object properties: surveyName: type: string thankYouMessage: type: string surveyType: type: string ownerEmailId: type: string pages: type: array items: type: object properties: questions: type: array items: type: object properties: title: type: string type: type: string required: type: boolean choices: type: array items: type: string minLabel: type: string maxLabel: type: string maxValue: oneOf: - type: number - type: string showTime: type: boolean showDate: type: boolean interval: type: number minValue: type: string contactRows: type: array items: type: object properties: required: type: boolean title: type: string type: type: string required: - required - title - type rows: type: array items: type: string contactUsMessage: type: string reviewSources: type: array items: type: string required: - title - type - choices - minLabel - required - maxValue - maxLabel - rows title: type: string required: - questions - title example: surveyName: Experience Survey thankYouMessage: Thank you for taking the survey! surveyType: traditional ownerEmailId: testmail@gmail.com pages: - questions: - title: Text1 type: text - title: Paragraph type: textarea - title: Page 2-optional questions: - title: Questionnumber1 type: checkbox required: true choices: - Choice 1 - Choice 2 - Choice 3 - title: Q2 type: dropdown choices: - Dropdown 1 - Dropdown 2 - Dropdown 3 - title: ratingQn type: rating minLabel: Strongly Disagree maxLabel: Strongly Agree maxValue: 10 - questions: - title: P3-Q1-Radio type: radio choices: - radio 1 - radio 2 - radio 3 - title: npsQn type: nps minLabel: Strongly Disagree - questions: - title: Datetime question type: datetime required: true showTime: true showDate: true interval: 60 minValue: '12' maxValue: '36' - title: Please enter your contact information type: contact required: true contactRows: - required: true title: First name type: text - required: true title: Email type: email - required: true title: Phone type: phone - title: Page 4 questions: - title: P4-Q1 type: matrixrating minLabel: Strongly Disagree maxLabel: Strongly Agree maxValue: 5 rows: - Row label 1 - Row label 2 - title: P4-Q2 type: matrixradio required: true choices: - c1 - c2 - c3 rows: - Row 1 - Row2 - title: p4-Q3 type: matrixdropdown required: true choices: - c1 - c2 - c3 rows: - Row label 1 - Row label 2 - title: Label type ques type: label - questions: - title: please review us on one of these sites type: review required: true contactUsMessage: ContactUs test message reviewSources: - Google - Facebook - CitySearch example: surveyName: Experience Survey thankYouMessage: Thank you for taking the survey! surveyType: traditional ownerEmailId: testmail@gmail.com pages: - questions: - title: Text1 type: text - title: Paragraph type: textarea - title: Page 2-optional questions: - title: Questionnumber1 type: checkbox required: true choices: - Choice 1 - Choice 2 - Choice 3 - title: Q2 type: dropdown choices: - Dropdown 1 - Dropdown 2 - Dropdown 3 - title: ratingQn type: rating minLabel: Strongly Disagree maxLabel: Strongly Agree maxValue: 10 - questions: - title: P3-Q1-Radio type: radio choices: - radio 1 - radio 2 - radio 3 - title: npsQn type: nps minLabel: Strongly Disagree - questions: - title: Datetime question type: datetime required: true showTime: true showDate: true interval: 60 minValue: '12' maxValue: '36' - title: Please enter your contact information type: contact required: true contactRows: - required: true title: First name type: text - required: true title: Email type: email - required: true title: Phone type: phone - title: Page 4 questions: - title: P4-Q1 type: matrixrating minLabel: Strongly Disagree maxLabel: Strongly Agree maxValue: 5 rows: - Row label 1 - Row label 2 - title: P4-Q2 type: matrixradio required: true choices: - c1 - c2 - c3 rows: - Row 1 - Row2 - title: p4-Q3 type: matrixdropdown required: true choices: - c1 - c2 - c3 rows: - Row label 1 - Row label 2 - title: Label type ques type: label - questions: - title: please review us on one of these sites type: review required: true contactUsMessage: ContactUs test message reviewSources: - Google - Facebook - CitySearch responses: '200': description: OK content: application/json: example: surveyId: 1234 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/2044Model' x-apiary-response-models: - $ref: '#/components/schemas/2044Model' - $ref: '#/components/schemas/2093Model' - $ref: '#/components/schemas/2045Model' - $ref: '#/components/schemas/2046Model' - $ref: '#/components/schemas/2047Model' - $ref: '#/components/schemas/2048Model' - $ref: '#/components/schemas/2049Model' - $ref: '#/components/schemas/2050Model' - $ref: '#/components/schemas/2051Model' - $ref: '#/components/schemas/2052Model' - $ref: '#/components/schemas/2053Model' - $ref: '#/components/schemas/2054Model' - $ref: '#/components/schemas/2055Model' - $ref: '#/components/schemas/2056Model' - $ref: '#/components/schemas/2057Model' - $ref: '#/components/schemas/2058Model' - $ref: '#/components/schemas/2059Model' - $ref: '#/components/schemas/2060Model' - $ref: '#/components/schemas/2061Model' - $ref: '#/components/schemas/2062Model' - $ref: '#/components/schemas/2063Model' - $ref: '#/components/schemas/2064Model' - $ref: '#/components/schemas/2065Model' - $ref: '#/components/schemas/2066Model' - $ref: '#/components/schemas/2067Model' - $ref: '#/components/schemas/2068Model' - $ref: '#/components/schemas/2069Model' - $ref: '#/components/schemas/2070Model' - $ref: '#/components/schemas/2071Model' - $ref: '#/components/schemas/2072Model' - $ref: '#/components/schemas/2073Model' - $ref: '#/components/schemas/2074Model' - $ref: '#/components/schemas/2092Model' - $ref: '#/components/schemas/2076Model' - $ref: '#/components/schemas/2077Model' - $ref: '#/components/schemas/2091Model' - $ref: '#/components/schemas/2079Model' - $ref: '#/components/schemas/2080Model' - $ref: '#/components/schemas/2081Model' - $ref: '#/components/schemas/2082Model' - $ref: '#/components/schemas/2083Model' - $ref: '#/components/schemas/2084Model' - $ref: '#/components/schemas/2085Model' - $ref: '#/components/schemas/2086Model' - $ref: '#/components/schemas/2087Model' - $ref: '#/components/schemas/2088Model' - $ref: '#/components/schemas/2094Model' - $ref: '#/components/schemas/2095Model' x-apiary-response-examples: error_2044: value: code: 2044 message: Survey already completed error_2093: value: code: 2093 message: Survey Field Type passed is unknown error_2045: value: code: 2045 message: Invalid Survey Type error_2046: value: code: 2046 message: Min Value is greater then Max Value error_2047: value: code: 2047 message: Survey Fields Missing! error_2048: value: code: 2048 message: Field Rows Missing error_2049: value: code: 2049 message: Interval can only be 30 min or 60 min error_2050: value: code: 2050 message: More than one location question cannot be present error_2051: value: code: 2051 message: More than one review question cannot be present error_2052: value: code: 2052 message: >- Review question should be present in the last page of the survey as a single question error_2053: value: code: 2053 message: Contact Fields are not present error_2054: value: code: 2054 message: Min Value out of range error_2055: value: code: 2055 message: Max Value out of range error_2056: value: code: 2056 message: >- Min and Max values can only be even numbers when the interval is 60 minutes error_2057: value: code: 2057 message: >- Either one of Min and Max values is missing in datetime type question error_2058: value: code: 2058 message: LocationIds are not present error_2059: value: code: 2059 message: Invalid type of contact question error_2060: value: code: 2060 message: reviewSources are not present for review type question error_2061: value: code: 2061 message: >- Pickone type of survey can only contain pickone type questions error_2062: value: code: 2062 message: >- Traditional type survey cannot contain these type questions error_2063: value: code: 2063 message: >- Pulse(NPS) Survey can only contain radio, text, textarea(paragraph), rating and nps type questions error_2064: value: code: 2064 message: >- First page of the survey must contain atleast one question except review question error_2065: value: code: 2065 message: There cannot be more than 3 sourceIds for review question error_2066: value: code: 2066 message: >- BusinessIds passed in the location type question are invalid error_2067: value: code: 2067 message: One of the locations passed in the request is not present error_2068: value: code: 2068 message: The locationIds are Non-Parseable error_2069: value: code: 2069 message: surveyName is Mandatory error_2070: value: code: 2070 message: Question Type cannot be blank error_2071: value: code: 2071 message: Invalid ownerEmailId error_2072: value: code: 2072 message: Choice cannot be a blank string error_2073: value: code: 2073 message: Logic type is Invalid! error_2074: value: code: 2074 message: Cannot contain a logic error_2092: value: code: 2092 message: Invalid Logic! error_2076: value: code: 2076 message: >- Value of the logic is not present in the choices of Question error_2077: value: code: 2077 message: Value of a questionLogic field cannot be blank error_2091: value: code: 2091 message: Operator Invalid error_2079: value: code: 2079 message: >- Only one Skip logic is allowed for text and textarea type questions error_2080: value: code: 2080 message: Display Logic Invalid! error_2081: value: code: 2081 message: Skip Logic Invalid! error_2082: value: code: 2082 message: The API returned an empty response. error_2083: value: code: 2083 message: Source is not integrated with the business error_2084: value: code: 2084 message: >- Opeartor must be present for logics other than the first display logic error_2085: value: code: 2085 message: Condition cannot be null! error_2086: value: code: 2086 message: Question Number cannot be null error_2087: value: code: 2087 message: Duplicate contact sub type question is present error_2088: value: code: 2088 message: Review Source already present error_2094: value: code: 2094 message: ReviewSources passed are invalid error_2095: value: code: 2095 message: ownerEmailId cannot be null examples: response: value: code: 2044 message: Survey already completed '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/1161Model' x-apiary-response-models: - $ref: '#/components/schemas/1161Model' - $ref: '#/components/schemas/1380Model' x-apiary-response-examples: error_1161: value: code: 1161 message: Invalid API key error_1380: value: code: 1380 message: Api key or session token missing examples: response: value: code: 1161 message: Invalid API key '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/1011Model' examples: response: value: code: 1011 message: Business id is invalid '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/89Model' examples: response: value: code: 89 message: Rate limit exceeded components: schemas: 2044Model: type: object properties: code: type: number message: type: string example: code: 2044 message: Survey already completed 1161Model: type: object properties: code: type: number message: type: string example: code: 1161 message: Invalid API key 1011Model: type: object properties: code: type: number message: type: string example: code: 1011 message: Business id is invalid 89Model: type: object properties: code: type: number message: type: string example: code: 89 message: Rate limit exceeded ````