Spaceship Contacts attributes API
The Contacts attributes API from Spaceship — 2 operation(s) for contacts attributes.
OpenAPI Specification
openapi: 3.0.0
info:
title: Spaceship.com Async Operations Contacts attributes API
contact:
email: support@spaceship.com
url: https://www.spaceship.com/about/contact-us/
description: "# Spaceship API\n\n## Authentication\n\nSpaceship API uses a combination of API key and API secret for authentication.\n\n### API key setup\nYou can generate your API key and secret in [API Manager](https://www.spaceship.com/application/api-manager/). Use the \"New API key\" button to set up a new API key and follow the guide to get started.\nAfter the key setup has been successful, it should appear on the API Manager application page.\n\n### API key usage\nAs shown in the example below, API consumers shall pass a valid API key and a corresponding API secret in the X-API-Secret headers.\nYou do not need to encode the API key and the API secret.\n```bash\ncurl -X GET '/api/resource' \\\n-H 'X-Api-Secret: F3brvQluT4s8aDB7PeFBH6qKHfH2xTKTneCjZbq3z2w7rj2vV6n_zhSvvJoQ' \\\n-H 'X-Api-Key: JdIS8QYFMZpVKupJtdc3'\n```\n\n## Asynchronous Operations\n\nSome API operations may take an extended period to complete. For these long-running operations, the API returns an HTTP 202 Accepted response with a `spaceship-async-operationid` header containing a unique operation identifier.\n\n### How Async Operations Work\n\n1. **Initiate Operation**: When you make a request that requires asynchronous processing (e.g., domain registration, transfer operations), the API immediately returns a 202 response.\n\n2. **Receive Operation ID**: The response includes the `spaceship-async-operationid` header with a unique identifier for tracking the operation.\n\n3. **Poll for Status**: Use the operation ID to poll the `/v1/async-operations/{operationId}` endpoint to check the current status of your operation.\n\n4. **Operation States**: Async operations can have the following statuses:\n - `pending` - The operation is still in progress\n - `success` - The operation completed successfully\n - `failed` - The operation encountered an error and could not complete\n\n### Example Workflow\n\n```bash\n# Step 1: Initiate an async operation (e.g., domain registration)\ncurl -X POST '/api/v1/domains/example.com' \\\n-H 'X-Api-Secret: YOUR_SECRET' \\\n-H 'X-Api-Key: YOUR_KEY' \\\n-H 'Content-Type: application/json' \\\n-d '{\n \"autoRenew\": false,\n \"years\": 1,\n \"privacyProtection\": {\n \"level\": \"high\",\n \"userConsent\": true\n },\n \"contacts\": {\n \"registrant\": \"CONTACT_ID\",\n \"admin\": \"CONTACT_ID\",\n \"tech\": \"CONTACT_ID\",\n \"billing\": \"CONTACT_ID\"\n }\n}'\n\n# Response: 202 Accepted\n# Headers: spaceship-async-operationid: abc123xyz\n\n# Step 2: Check operation status\ncurl -X GET '/api/v1/async-operations/abc123xyz' \\\n-H 'X-Api-Secret: YOUR_SECRET' \\\n-H 'X-Api-Key: YOUR_KEY'\n\n# Response includes:\n# - status: \"pending\" | \"success\" | \"failed\"\n# - type: Operation type (e.g., \"domains_Create\")\n# - details: Additional information about the operation\n# - createdAt: Timestamp when operation was created\n# - modifiedAt: Timestamp of last status update\n```\n\n### Permissions \n\n - <b id=\"scopes/domains:read\">domains:read</b> - Read domain information and check configuration\n- <b id=\"scopes/domains:write\">domains:write</b> - Manage domains and domain settings\n- <b id=\"scopes/domains:transfer\">domains:transfer</b> - Transfer domains in and out\n- <b id=\"scopes/domains:billing\">domains:billing</b> - Manage domains billing operations\n- <b id=\"scopes/contacts:write\">contacts:write</b> - Save contact details\n- <b id=\"scopes/contacts:read\">contacts:read</b> - Read contact details\n- <b id=\"scopes/dnsrecords:write\">dnsrecords:write</b> - Write DNS resource records\n- <b id=\"scopes/dnsrecords:read\">dnsrecords:read</b> - Read DNS resource records\n- <b id=\"scopes/asyncoperations:read\">asyncoperations:read</b> - Read async operations details\n- <b id=\"scopes/sellerhub:read\">sellerhub:read</b> - Read SellerHub Domains\n- <b id=\"scopes/sellerhub:write\">sellerhub:write</b> - Write SellerHub Domains"
version: 1.0.0
x-logo:
url: https://spaceship-cdn.com/spaceship-api-doc-assets/logo.svg
servers:
- url: https://spaceship.dev/api
description: The main server for the Spaceship External API
variables: {}
security:
- apiKey: []
apiSecret: []
tags:
- name: Contacts attributes
paths:
/v1/contacts/attributes:
put:
operationId: saveContactAttributes
summary: Save contact attributes
description: "Save contact attributes and return the generated contact ID.\n\n### Required Permissions \n\n - <a href=\"#scopes/contacts:write\">contacts:write</a>\n\n### Rate Limits \n\n * The limit for saving contact attribute details is 300 requests per user, within 300 seconds."
parameters: []
responses:
'200':
description: The request was successful.
content:
application/json:
schema:
$ref: '#/components/schemas/Attributes.ContactsAttributesResponse'
'400':
description: The request is invalid.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'401':
description: The user's request was not authorized properly.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The user's request not allowed to perform this action with the current scopes.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: The requested object was not found.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ObjectNotFoundError'
'422':
description: The entity is unprocessable.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
'429':
description: The response indicates that the rate limit for the API has been exceeded. It includes details about the rate limit, like the number of requests left and the time the rate limit window resets.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
X-RateLimit-Limit:
required: true
description: Request limit per the allotted time window
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
X-RateLimit-Remaining:
required: true
description: The number of requests left for the time window
schema:
type: integer
format: int32
minimum: 0
maximum: 2147483647
X-RateLimit-Reset:
required: true
description: The UTC date/time when the current rate limit window resets
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
Retry-After:
required: true
description: The number of seconds inndicating how long the client ought to wait before making a follow-up request
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitError'
'500':
description: The infrastructure encountered an error.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnexpectedError'
tags:
- Contacts attributes
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeDetails'
description: Details
x-scopes:
- contacts:write
x-codeSamples:
- lang: javascript
source: "const url = 'https://spaceship.dev/api/v1/contacts/attributes';\nconst options = {\n method: 'PUT',\n headers: {\n 'X-API-Key': 'REPLACE_KEY_VALUE',\n 'X-API-Secret': 'REPLACE_KEY_VALUE',\n 'content-type': 'application/json'\n },\n body: JSON.stringify({type: 'string'})\n};\n\nfetch(url, options)\n .then(res => res.json())\n .then(json => console.log(json))\n .catch(err => console.error(err));"
- lang: php
source: "<?php\nrequire_once('vendor/autoload.php');\n\n$client = new \\GuzzleHttp\\Client();\n\n$response = $client->request('PUT', 'https://spaceship.dev/api/v1/contacts/attributes', [\n 'body' => '{\"type\":\"string\"}',\n 'headers' => [\n 'X-API-Key' => 'REPLACE_KEY_VALUE',\n 'X-API-Secret' => 'REPLACE_KEY_VALUE',\n 'content-type' => 'application/json',\n ],\n]);\n\necho $response->getBody();"
- lang: python
source: "import requests\n\nurl = \"https://spaceship.dev/api/v1/contacts/attributes\"\n\npayload = { \"type\": \"string\" }\nheaders = {\n \"X-API-Key\": \"REPLACE_KEY_VALUE\",\n \"X-API-Secret\": \"REPLACE_KEY_VALUE\",\n \"content-type\": \"application/json\"\n}\n\nresponse = requests.put(url, json=payload, headers=headers)\n\nprint(response.text)"
- lang: shell
source: "curl --request PUT \\\n --url https://spaceship.dev/api/v1/contacts/attributes \\\n --header 'X-API-Key: REPLACE_KEY_VALUE' \\\n --header 'X-API-Secret: REPLACE_KEY_VALUE' \\\n --header 'content-type: application/json' \\\n --data '{\"type\":\"string\"}'"
/v1/contacts/attributes/{contact}:
get:
operationId: readAttributeDetails
summary: Read attribute details
description: "Read attribute details by contact ID.\n\n### Required Permissions \n\n - <a href=\"#scopes/contacts:read\">contacts:read</a>\n\n### Rate Limits \n\n * The limit for listing contact attribute details is 5 requests per attribute, within 300 seconds."
parameters:
- name: contact
in: path
required: true
schema:
type: string
example: 1ZdMXpapqp9sle5dl8BlppTJXAzf5
minLength: 27
maxLength: 32
pattern: '[a-zA-Z0-9]+'
description: Contact ID
responses:
'200':
description: The request was successful.
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeDetails'
'400':
description: The request is invalid.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ErrorDetail'
'401':
description: The user's request was not authorized properly.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
'403':
description: The user's request not allowed to perform this action with the current scopes.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ForbiddenError'
'404':
description: The requested object was not found.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ObjectNotFoundError'
'422':
description: The entity is unprocessable.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ValidationError'
'429':
description: The response indicates that the rate limit for the API has been exceeded. It includes details about the rate limit, like the number of requests left and the time the rate limit window resets.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
X-RateLimit-Limit:
required: true
description: Request limit per the allotted time window
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
X-RateLimit-Remaining:
required: true
description: The number of requests left for the time window
schema:
type: integer
format: int32
minimum: 0
maximum: 2147483647
X-RateLimit-Reset:
required: true
description: The UTC date/time when the current rate limit window resets
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
Retry-After:
required: true
description: The number of seconds inndicating how long the client ought to wait before making a follow-up request
schema:
type: integer
format: int32
minimum: 1
maximum: 2147483647
content:
application/problem+json:
schema:
$ref: '#/components/schemas/RateLimitError'
'500':
description: The infrastructure encountered an error.
headers:
spaceship-error-code:
required: true
schema:
$ref: '#/components/schemas/errorCode'
spaceship-operation-id:
required: true
schema:
$ref: '#/components/schemas/operationId'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/UnexpectedError'
tags:
- Contacts attributes
x-scopes:
- contacts:read
x-codeSamples:
- lang: javascript
source: "const url = 'https://spaceship.dev/api/v1/contacts/attributes/1ZdMXpapqp9sle5dl8BlppTJXAzf5';\nconst options = {\n method: 'GET',\n headers: {'X-API-Key': 'REPLACE_KEY_VALUE', 'X-API-Secret': 'REPLACE_KEY_VALUE'}\n};\n\nfetch(url, options)\n .then(res => res.json())\n .then(json => console.log(json))\n .catch(err => console.error(err));"
- lang: php
source: "<?php\nrequire_once('vendor/autoload.php');\n\n$client = new \\GuzzleHttp\\Client();\n\n$response = $client->request('GET', 'https://spaceship.dev/api/v1/contacts/attributes/1ZdMXpapqp9sle5dl8BlppTJXAzf5', [\n 'headers' => [\n 'X-API-Key' => 'REPLACE_KEY_VALUE',\n 'X-API-Secret' => 'REPLACE_KEY_VALUE',\n ],\n]);\n\necho $response->getBody();"
- lang: python
source: "import requests\n\nurl = \"https://spaceship.dev/api/v1/contacts/attributes/1ZdMXpapqp9sle5dl8BlppTJXAzf5\"\n\nheaders = {\n \"X-API-Key\": \"REPLACE_KEY_VALUE\",\n \"X-API-Secret\": \"REPLACE_KEY_VALUE\"\n}\n\nresponse = requests.get(url, headers=headers)\n\nprint(response.text)"
- lang: shell
source: "curl --request GET \\\n --url https://spaceship.dev/api/v1/contacts/attributes/1ZdMXpapqp9sle5dl8BlppTJXAzf5 \\\n --header 'X-API-Key: REPLACE_KEY_VALUE' \\\n --header 'X-API-Secret: REPLACE_KEY_VALUE'"
components:
schemas:
Attributes.ContactsAttributesResponse:
type: object
required:
- contactId
properties:
contactId:
$ref: '#/components/schemas/contactId'
operationId:
type: string
maxLength: 16
pattern: ^[a-z0-9]{16}$
description: 16-characters unique identifier of the operation
RateLimitError:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
contactId:
type: string
example: 1ZdMXpapqp9sle5dl8BlppTJXAzf5
minLength: 27
maxLength: 32
pattern: '[a-zA-Z0-9]+'
description: Contact ID
ForbiddenError:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
ValidationError:
type: object
required:
- detail
- data
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
data:
type: array
items:
type: object
properties:
field:
type: string
example: name
pattern: ^[\s|\S]*$
description: The path to the field that caused the validation error
readOnly: true
details:
type: string
example: The domain name contains invalid characters
pattern: ^[\s|\S]*$
description: A specific message about what is wrong with the field
readOnly: true
required:
- field
- details
description: A detailed list of validation errors
readOnly: true
ObjectNotFoundError:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
ErrorDetail:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
errorCode:
type: string
maxLength: 255
pattern: ^(business|application|infrastructure)(\.[a-zA-Z]+)+$
description: The dot-separated error code indicating the type of the problem occurred
UnauthorizedError:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
AttributeDetails:
type: object
required:
- type
properties:
type:
type: string
minLength: 2
maxLength: 32
pattern: \w+
discriminator:
propertyName: type
mapping:
ca: '#/components/schemas/CaAttributeDetails'
us: '#/components/schemas/UsAttributeDetails'
description: Attribute details
UnexpectedError:
type: object
required:
- detail
properties:
detail:
type: string
pattern: ^[\s|\S]*$
description: A general message about the exception
readOnly: true
securitySchemes:
apiKey:
type: apiKey
in: header
name: X-API-Key
description: API key for authenticating requests, with a set of scopes (permissions) defined by the user at the time of creation.
apiSecret:
type: apiKey
in: header
name: X-API-Secret
description: API secret for authenticating requests must be set together with the API key.
x-scopes:
domains:read: Read domain information and check configuration
domains:write: Manage domains and domain settings
domains:transfer: Transfer domains in and out
domains:billing: Manage domains billing operations
contacts:write: Save contact details
contacts:read: Read contact details
dnsrecords:write: Write DNS resource records
dnsrecords:read: Read DNS resource records
asyncoperations:read: Read async operations details
sellerhub:read: Read SellerHub Domains
sellerhub:write: Write SellerHub Domains
x-tagGroups:
- name: Domains
tags:
- Domain Management
- Domain Availability
- Domain Settings
- Personal Nameservers
- Domain Transfer
- name: Contacts
tags:
- Contacts
- Contacts attributes
- name: DNS
tags:
- DNS records
- name: SellerHub
tags:
- SellerHub
- name: Async Operations
tags:
- Async Operations