openapi: 3.0.3
info:
  title: Rackspace Customer Service API
  version: '1.0'
  description: >-
    The Rackspace Customer Service API exposes customer account, contact, and
    metadata operations. It lets internal users and integrations look up
    customer accounts the caller has access to (via tenant assignment),
    inspect account and customer history, and read service-level metadata
    associated with a customer resource.
  contact:
    name: Rackspace Technology
    url: https://www.rackspace.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  x-generated-from: documentation
  x-source-url: https://github.com/rackerlabs/docs-customer-service
  x-last-validated: '2026-05-05'
servers:
  - url: https://accounts.api.rackspacecloud.com
    description: Rackspace Customer Service production endpoint.
security:
  - AuthToken: []
tags:
  - name: CustomerAccounts
    description: Customer-account lookup and history operations.
  - name: Contacts
    description: Customer contact operations.
  - name: Metadata
    description: Resource-level customer metadata.
paths:
  /v1/customer_accounts:
    get:
      operationId: getListOfCustomerAccounts
      summary: Get List Of Customer Accounts
      description: Returns the list of customer accounts the caller has access to based on their tenants.
      tags: [CustomerAccounts]
      responses:
        '200':
          description: Customer accounts returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CustomerAccountList' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customer_accounts/{rcn}:
    parameters:
      - $ref: '#/components/parameters/RCN'
    get:
      operationId: getCustomerAccount
      summary: Get Customer Account
      description: Returns details about a single customer account.
      tags: [CustomerAccounts]
      responses:
        '200':
          description: Customer account returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CustomerAccount' }
        '404': { $ref: '#/components/responses/NotFound' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customer_accounts/{rcn}/status_history:
    parameters:
      - $ref: '#/components/parameters/RCN'
    get:
      operationId: getListOfCustomerAccountStatusHistory
      summary: Get List Of Customer Account Status History
      description: Returns the status-change history for the customer account.
      tags: [CustomerAccounts]
      responses:
        '200':
          description: Status history returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AccountStatusHistory' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customer_accounts/{rcn}/history:
    parameters:
      - $ref: '#/components/parameters/RCN'
    get:
      operationId: getListOfCustomerAccountHistory
      summary: Get List Of Customer Account History
      description: Returns the change history for the customer account.
      tags: [CustomerAccounts]
      responses:
        '200':
          description: Account history returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AccountHistory' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customers/{customerId}/history:
    parameters:
      - $ref: '#/components/parameters/CustomerId'
    get:
      operationId: getListOfCustomerHistory
      summary: Get List Of Customer History
      description: Returns the change history for the customer.
      tags: [CustomerAccounts]
      responses:
        '200':
          description: Customer history returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CustomerHistory' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customer_accounts/{rcn}/contacts:
    parameters:
      - $ref: '#/components/parameters/RCN'
    get:
      operationId: getListOfContacts
      summary: Get List Of Contacts
      description: Returns the list of contacts associated with the customer account.
      tags: [Contacts]
      responses:
        '200':
          description: Contacts returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ContactList' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/customer_accounts/{rcn}/contacts/{contactId}:
    parameters:
      - $ref: '#/components/parameters/RCN'
      - in: path
        name: contactId
        required: true
        schema: { type: string }
    get:
      operationId: getContact
      summary: Get Contact
      description: Returns a single contact by ID.
      tags: [Contacts]
      responses:
        '200':
          description: Contact returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Contact' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/{resourceType}/{resourceId}/metadata:
    parameters:
      - $ref: '#/components/parameters/ResourceType'
      - $ref: '#/components/parameters/ResourceId'
    get:
      operationId: getListOfAllMetadataForResource
      summary: Get List Of All Metadata For Resource
      description: Returns all metadata key-value pairs attached to the specified resource.
      tags: [Metadata]
      responses:
        '200':
          description: Metadata returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MetadataList' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/{resourceType}/{resourceId}/metadata/{key}:
    parameters:
      - $ref: '#/components/parameters/ResourceType'
      - $ref: '#/components/parameters/ResourceId'
      - in: path
        name: key
        required: true
        schema: { type: string }
    get:
      operationId: getSpecificMetadata
      summary: Get Specific Metadata
      description: Returns the metadata entry identified by the supplied key.
      tags: [Metadata]
      responses:
        '200':
          description: Metadata entry returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Metadata' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
  /v1/{resourceType}/{resourceId}/metadata/{key}/details:
    parameters:
      - $ref: '#/components/parameters/ResourceType'
      - $ref: '#/components/parameters/ResourceId'
      - in: path
        name: key
        required: true
        schema: { type: string }
    get:
      operationId: getDetailsForSpecificMetadata
      summary: Get Details For Specific Metadata
      description: Returns extended detail about the metadata entry, including who created it and when.
      tags: [Metadata]
      responses:
        '200':
          description: Metadata details returned.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/MetadataDetails' }
      x-microcks-operation: { delay: 0, dispatcher: FALLBACK }
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
  parameters:
    RCN:
      in: path
      name: rcn
      required: true
      description: The Rackspace Customer Number (RCN) identifying the customer account.
      schema: { type: string }
    CustomerId:
      in: path
      name: customerId
      required: true
      schema: { type: string }
    ResourceType:
      in: path
      name: resourceType
      required: true
      description: Resource type the metadata is attached to (for example, customer_accounts).
      schema: { type: string }
    ResourceId:
      in: path
      name: resourceId
      required: true
      schema: { type: string }
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    Unauthorized:
      description: Unauthorized.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    Forbidden:
      description: Forbidden.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
    NotFound:
      description: Not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Fault' }
  schemas:
    CustomerAccount:
      title: CustomerAccount
      type: object
      properties:
        rcn: { type: string, description: Rackspace Customer Number. }
        name: { type: string }
        status: { type: string }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        customerSegment: { type: string }
        billingCountry: { type: string }
        contacts:
          type: array
          items: { $ref: '#/components/schemas/Contact' }
        metadata:
          type: array
          items: { $ref: '#/components/schemas/Metadata' }
    CustomerAccountList:
      title: CustomerAccountList
      type: object
      properties:
        customer_accounts:
          type: array
          items: { $ref: '#/components/schemas/CustomerAccount' }
        totalEntries: { type: integer }
    Contact:
      title: Contact
      type: object
      properties:
        id: { type: string }
        firstName: { type: string }
        lastName: { type: string }
        email: { type: string, format: email }
        phone: { type: string }
        roles:
          type: array
          items: { type: string }
        primary: { type: boolean }
    ContactList:
      title: ContactList
      type: object
      properties:
        contacts:
          type: array
          items: { $ref: '#/components/schemas/Contact' }
    Metadata:
      title: Metadata
      type: object
      properties:
        key: { type: string }
        value: { type: string }
        category: { type: string }
    MetadataList:
      title: MetadataList
      type: object
      properties:
        metadata:
          type: array
          items: { $ref: '#/components/schemas/Metadata' }
    MetadataDetails:
      title: MetadataDetails
      allOf:
        - $ref: '#/components/schemas/Metadata'
        - type: object
          properties:
            createdAt: { type: string, format: date-time }
            createdBy: { type: string }
            updatedAt: { type: string, format: date-time }
            updatedBy: { type: string }
    AccountStatusHistory:
      title: AccountStatusHistory
      type: object
      properties:
        history:
          type: array
          items:
            type: object
            properties:
              status: { type: string }
              changedAt: { type: string, format: date-time }
              changedBy: { type: string }
              reason: { type: string }
    AccountHistory:
      title: AccountHistory
      type: object
      properties:
        history:
          type: array
          items:
            type: object
            properties:
              field: { type: string }
              previousValue: { type: string }
              newValue: { type: string }
              changedAt: { type: string, format: date-time }
              changedBy: { type: string }
    CustomerHistory:
      allOf:
        - $ref: '#/components/schemas/AccountHistory'
    Fault:
      title: Fault
      type: object
      properties:
        code: { type: integer }
        message: { type: string }
        details: { type: string }