anchor.diff:  
   You don't need to worry about most of those links for now, we'll learn about them as we go.
   
  -== Pick a team
  +== Create a submission
  +
  +The submission system allows you to build up your submission over time and send it to the archives when you are ready.
  +The first step is to create a submission.
  +
  +=== Pick a team
   
   Every submission is owned by a _team_. A team is a group of people, working together on the same data. How you use this
  -is up to you. You could create a team for just yourself, everyone in a lab, or one for all collaborators on At this stage of development, the API doesn't restrict what team you use.
  -A future update will add support for team membership and administration. Until then, you can use any team name you like.
  -
  -A team object is structured like this:
  +is up to you. You could create a team for just yourself, everyone in a lab, or one for all collaborators on a project.
  +
  +At this stage of development the API doesn't restrict what team you use. A future update will add support for team
  +membership and administration. Until then, you can use any team name you like.
  +
  +A team document is structured like this:
   
   `{"name" : "my-team"}`
   
   At present, you also need to provide a submitter object when creating a submission. In future versions this will be
  -taken from your log in information, but for now you need to provide a submitter object:
  +taken from your log in information, but for now you need to provide a submitter document:
   
   `{"email": "alice@example.com"}`
   
  -== Create a submission
  +=== POSTing a submission
   
   Using the link labelled `submissions:create`, `POST` a document containing a team and a submitter to create
   a submission:
  
positive.code: the record within the submission system. Each alias should be unique within the records of that type owned by a team.
  Using an alias for a second time in another submission will cause the record to be overwritten.
  
  === Sample documents
  
  The description of a sample should normally include a taxonomic code to describe the species classification. This should
  be an entry from the taxonomy database curated at https://www.ncbi.nlm.nih.gov/taxonomy/[NCBI]. EMBL-EBI provide a
  http://www.ebi.ac.uk/ena/browse/taxonomy-service[service] to search for and look up taxonomic entries and this is used
  when the submission interface checks sample documents.
  
  We will accept sample records for display in https://www.ebi.ac.uk/biosamples/[BioSamples] without a taxon ID, but
  you will not be able to use the sample record when submitting data the experimental data archives without a taxon ID.
  
  If you use a taxon ID, it must be one marked as 'submittable' in the taxonomy database.
  
  
  === Validation
  
  Descriptive data is checked at two points during submission:
  
   1. When sent to the API server, through `POST`, `PUT` and `PATCH` requests. At this point the sent must be match the expected syntax, and be identified with an alias.
   2. Once accepted by the API server, it is sent to a suite of validators to ensure it meets the requirements of the relevant archives or project.
  
  The second stage of validation is more in depth, and takes longer. Clients can poll for `ValidationResults` for each
  submitted document, and for a submission. You will not be able to complete a submission until validation
  have completed and no errors have been found.
  
  TODO add example of getting validation results
  
  === Updating a sample
  
  
negative.code: If you need to update the information of any of the records submitted, create an new submission and add a document,
  following the same process as before. Using the same team and alias will ensure that the archive records are updated.
  
  == When things go wrong
  
  Successful requests will return a HTTP status code in `20X` range
  (see the <<submission_api.adoc#_http_status_codes,reference docs>>). When something goes wrong, there will be an
  error message to explain the problem. There's an explanation of each error type in the <<submission_api.adoc#_errors,reference docs>>.
  
  Errors can normally be resolved by correcting the content or format of your request. Please get in touch if the cause
  of the problem isn't clear. *TODO* add helpdesk link
  
  == Where to go next?
  
  You can find more in-depth documentation on the API in the <<submission_api.adoc#,reference documentation>>.