> ## Documentation Index
> Fetch the complete documentation index at: https://platform.tatango.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Keyword Availability on Shortcode

> This endpoint checks the availability of a keyword on the account's shortcode.

## Request URL

```http theme={null}
POST https://app.tatango.com/api/v2/shortcodes/{ID}/test_keyword
```

<Tip>
  ### FAQs

  **What are the limitations for a keyword?**

  * A keyword must contain at least two characters and no more than 15 characters.
  * Keywords are not case sensitive. `FOO` will match `foo` and `FOO` and `Foo`.
  * You can't use obscene words. We're not going to spell them out here.

  **Are keywords case sensitive?**

  * No. The system checks for duplicate keywords by transforming all keywords to uppercase before performing matching algorithms.

  **What happens if the keyword isn't available?**

  * The response from the API will be a 422 error with the response body looking like this:
    * `{"status":"error","error":"invalid keyword names: EXISTINGKW"}`

  **What happens if the keyword isn't available?**

  * Yes. By utilizing this endpoint. The response will either be:
    * `200 OK` with the response body looking like this: `{"status":"OK","keyword_name":"available"}`
    * `200 OK` with the response body looking like this: `{"status":"OK","keyword_name":"unavailable","error":"Name is in use"}`.
</Tip>


## OpenAPI

````yaml POST /api/v2/shortcodes/{ID}/test_keyword
openapi: 3.1.0
info:
  title: Tatango Legacy v2 API
  description: Tatango legacy v2 API endpoints for existing integrations.
  version: 2.0.0
servers:
  - url: https://app.tatango.com
security:
  - basicAuth: []
paths:
  /api/v2/shortcodes/{ID}/test_keyword:
    post:
      tags:
        - Shortcodes
      summary: Testing Keyword Availability on Shortcode
      description: >-
        This endpoint checks the availability of a keyword on the account's
        shortcode.
      parameters:
        - name: ID
          in: path
          description: ID of the shortcode
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                keyword_name:
                  type: string
                  description: Keyword name to test
              required:
                - keyword_name
      responses:
        '200':
          description: Keyword availability check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestKeywordAvailabilityResponse'
              examples:
                available:
                  summary: Keyword is available
                  value:
                    status: OK
                    keyword_name: available
                unavailable:
                  summary: Keyword is unavailable
                  value:
                    status: OK
                    keyword_name: unavailable
                    error: Name is in use
        '422':
          description: Invalid keyword
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                status: error
                error: 'invalid keyword names: EXISTINGKW'
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >-
            curl "https://app.tatango.com/api/v2/shortcodes/ID/test_keyword" -X
            POST \
              -H "Accept: application/json" \
              -H "Content-Type: application/json" \
              -u emailaddress@mydomain.com:my_api_key \
              -d '{"keyword_name": "TESTKEYWORD"}'
        - lang: Ruby
          label: Ruby
          source: >-
            require 'net/http'

            require 'uri'

            require 'json'


            uri =
            URI.parse('https://app.tatango.com/api/v2/shortcodes/ID/test_keyword')

            http = Net::HTTP.new(uri.host, uri.port)

            request = Net::HTTP::Post.new(uri.request_uri)

            request.basic_auth("emailaddress@mydomain.com", "my_api_key")

            request.body = JSON.generate({keyword_name: "TESTKEYWORD"})

            response = http.request(request)
        - lang: JavaScript
          label: JavaScript
          source: >-
            var request = new XMLHttpRequest();

            request.open('POST',
            'https://app.tatango.com/api/v2/shortcodes/ID/test_keyword', false);

            request.setRequestHeader('Content-Type', 'application/json');

            request.setRequestHeader('Authorization', 'Basic ' +
            btoa('emailaddress@mydomain.com:my_api_key'));

            var data = JSON.stringify({keyword_name: 'TESTKEYWORD'});

            request.send(data);
components:
  schemas:
    TestKeywordAvailabilityResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        keyword_name:
          type: string
          enum:
            - available
            - unavailable
          example: available
        error:
          type: string
          example: Name is in use
      required:
        - status
        - keyword_name
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          example: error
        error:
          type: string
          example: This API key is disabled
      required:
        - status
        - error
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Tatango authenticates API requests by validating an API key passed via
        HTTP Basic Authentication. Use your login email as the username and your
        API key as the password.

````