Services API

Service attributes

Name Description
id A unique identifier
name A human-readable name
sid A string identifier that can be used in URLs (always lowercase)
description A human-readable description of the one-click service
setup_description Describes setup requirements (optional)
requires_setup Flag indicating whether setup is required
default_subdomain The default subdomain used when creating DNS records
created_at When the service was first added to DNSimple
updated_at When the service was last changed in DNSimple
settings A list of objects describing each setting that requires configuration

Service Setting attributes

Name Description
name The form name for the setting
label The human-readable label value
append Additional text to append to the input field
description Description of the setting
example An example value
password Set to true if the value is a password (and thus should be not visible in the field)

List services

GET /services

Example

List all services.

curl -H 'Authorization: Bearer <token>' \
     -H 'Accept: application/json' \
     https://api.dnsimple.com/v2/services

Response

{
  "data": [
    {
      "id": 1,
      "name": "Service 1",
      "sid": "service1",
      "description": "First service example.",
      "setup_description": null,
      "requires_setup": false,
      "default_subdomain": null,
      "created_at": "2014-02-14T19:15:19Z",
      "updated_at": "2016-03-04T09:23:27Z",
      "settings": [

      ]
    },
    {
      "id": 2,
      "name": "Service 2",
      "sid": "service2",
      "description": "Second service example.",
      "setup_description": null,
      "requires_setup": true,
      "default_subdomain": null,
      "created_at": "2014-02-14T19:15:19Z",
      "updated_at": "2016-03-04T09:23:27Z",
      "settings": [
        {
          "name": "username",
          "label": "Service 2 Account Username",
          "append": ".service2.com",
          "description": "Your Service2 username is used to connect services to your account.",
          "example": "username",
          "password": false
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 30,
    "total_entries": 2,
    "total_pages": 1
  }
}

Sorting

For general information about sorting, please refer to the main guide.

Name Description
id Sort services by ID
sid Sort services by string ID (alphabetical order)

The default sorting policy is by ascending id.

Get a service

GET /services/:service

Parameters

Name Type Description
:service string, integer The service name or id

Example

Get the service with ID 1.

curl -H 'Authorization: Bearer <token>' \
     -H 'Accept: application/json' \
     https://api.dnsimple.com/v2/services/1

Response

{
  "data": {
    "id": 1,
    "name": "Service 1",
    "sid": "service1",
    "description": "First service example.",
    "setup_description": null,
    "requires_setup": true,
    "default_subdomain": null,
    "created_at": "2014-02-14T19:15:19Z",
    "updated_at": "2016-03-04T09:23:27Z",
    "settings": [
      {
        "name": "username",
        "label": "Service 1 Account Username",
        "append": ".service1.com",
        "description": "Your Service 1 username is used to connect services to your account.",
        "example": "username",
        "password": false
      }
    ]
  }
}