Domains
A domain is a DNS domain or “the part behind the @” in an email address that is associated with a Teamwire organisation. Users and admins registering with an email address with this domain will be associated with its organisation.
Manage the domains associated with an organisation
Add a domain to an organisation
POST /v<api_version>/admin/domains/
Access restrictions
- Only Superadmins can call this endpoint.
- Superadmins must have the allow_modify_domains permission.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
POST data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
organisation_id |
Number | No | Superadmins | The ID of the organisation to add the domain to. |
domain |
String | No | Superadmins | The DNS domain name to associate with the organisation. It will be converted to lowercase automatically. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the added domain is returned as a JSON object as described for the GET request. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) the calling admin is not a Superadmin. |
| 409 (Conflict) | The request failed because either a.) the organisation to add the domain to has been disabled or b.) the domain already belongs to this or another organisation. |
| 422 (Unprocessable entity) | The request failed because the specified organisation could not be found. |
Return a list of all domains or details about a particular domain
GET /v<api_version>/admin/domains/
GET /v<api_version>/admin/domains/<domain_id>/
Access restrictions
- Admins and Superadmins must have the allow_view_domains permission.
- Admins can request details of domains in their own organisation only.
- Superadmins can request details of domains in any organisation.
- If no domain_id is specified:
- admins will receive a list of domains in their own organisation only.
- Superadmins will receive a list of domains in all organisations.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| domain_id | Integer | Yes | All admins | The ID of a particular domain for which details should be returned. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Information about the domain is returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) or b.) the admin is not a Superadmin and a domain was specified that does not belong to the admin’s organisation. |
| 404 (Not found) | The request failed because the specified domain could not be found. |
| 409 (Conflict) | The request failed because the organisation the domain belongs to has been disabled. |
If a domain ID was specified and the request was successful, a single JSON object with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
identifier |
Number | All admins | The domain’s ID. |
domain |
String | All admins | The domain name. |
organisation |
String | All admins | The name of the organisation the domain belongs to. |
organisation_id |
Number | All admins | The ID of the organisation the domain belongs to. |
users |
Number | All admins | The number of users with email addresses in this domain. |
admins |
Number | All admins | The number of admins with email addresses in this domain. |
org_domain_count |
Number | All admins | The total number of domains in the organisation. |
created_at |
String | All admins | A timestamp indicating when the API key was created. |
If no domain ID was specified and the request was successful, the JSON structure returned will be an array of JSON objects with elements as described above.
Remove a domain from a Teamwire organisation
DELETE /v<api_version>/admin/domains/<domain_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_domains permission.
- Admins can remove domains from their own organisation only.
- Superadmins can remove domains from any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| domain_id | Number | No | All admins | The ID of the domain to remove from its organisation. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The domain has been removed from the organisation. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled, b.) the admin is not a Superadmin and a domain was specified that does not belong to the admin’s organisation, c.) there are users or admins with email addresses in this domain that will have to be deleted first or d.) this is the last remaining domain in the organisation that can only be deleted by deleting the entire organisation. |
| 404 (Not found) | The request failed because the domain could not be found. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
Validates DNS domain names
Check whether a domain name is a valid DNS domain name
GET /v<api_version>/admin/domainvalidation/<domain>/
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| domain | String | No | All admins | The domain name to validate. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The domain name is a valid DNS domain name. |
| 404 (Not found) | The domain name does not seem to be a valid DNS domain name. |
| 504 (Gateway timeout) | The domain name could not be validated because DNS lookups are currently unavailable. |